politty 0.4.6 → 0.4.8

package/dist/{schema-extractor-CVf0J4An.d.cts → arg-registry-BDybpyo5.d.cts}

@@ -1,4 +1,3 @@
-import { n as CompletionMeta } from "./arg-registry-BNoIwnNr.cjs";
 import { z } from "zod";
 
 //#region src/lazy.d.ts
@@ -58,6 +57,10 @@ declare function lazy<T extends AnyCommand>(meta: T, load: () => Promise<AnyComm
  * ```
  */
 interface GlobalArgs {}
+/**
+ * Detect empty interface (used for GlobalArgs declaration merging)
+ */
+type IsEmpty<T> = keyof T extends never ? true : false;
 /**
  * Example definition for a command
  */
@@ -99,6 +102,17 @@ interface CleanupContext<TArgs = unknown> {
   /** Error if command execution failed */
   error?: Error | undefined;
 }
+/**
+ * Context provided to global setup function (runMain/runCommand level)
+ */
+interface GlobalSetupContext {}
+/**
+ * Context provided to global cleanup function (runMain/runCommand level)
+ */
+interface GlobalCleanupContext {
+  /** Error if command execution failed */
+  error?: Error | undefined;
+}
 /**
  * Base command interface (shared properties)
  * @template TArgsSchema - The Zod schema type for arguments
@@ -186,6 +200,10 @@ interface MainOptions {
   logger?: Logger;
   /** Global args schema (shared across all subcommands) */
   globalArgs?: ArgsSchema;
+  /** Global setup hook (runs before command execution) */
+  setup?: ((context: GlobalSetupContext) => void | Promise<void>) | undefined;
+  /** Global cleanup hook (runs after command execution, always executes even on error) */
+  cleanup?: ((context: GlobalCleanupContext) => void | Promise<void>) | undefined;
 }
 /**
  * Options for runCommand (programmatic/test usage)
@@ -201,6 +219,10 @@ interface RunCommandOptions {
   logger?: Logger;
   /** Global args schema (shared across all subcommands) */
   globalArgs?: ArgsSchema;
+  /** Global setup hook (runs before command execution) */
+  setup?: ((context: GlobalSetupContext) => void | Promise<void>) | undefined;
+  /** Global cleanup hook (runs after command execution, always executes even on error) */
+  cleanup?: ((context: GlobalCleanupContext) => void | Promise<void>) | undefined;
 }
 /**
  * Log level type
@@ -265,115 +287,173 @@ interface RunResultFailure {
  */
 type RunResult<T = unknown> = RunResultSuccess<T> | RunResultFailure;
 //#endregion
-//#region src/core/schema-extractor.d.ts
+//#region src/core/arg-registry.d.ts
 /**
- * Resolved metadata for an argument field
+ * Built-in completion types
  */
-interface ResolvedFieldMeta {
-  /** Field name (camelCase, as defined in schema) */
-  name: string;
-  /** CLI option name (kebab-case, for command line usage) */
-  cliName: string;
-  /** Short alias (e.g., 'v' for --verbose) */
-  alias?: string | undefined;
+type CompletionType = "file" | "directory" | "none";
+/**
+ * Custom completion specification
+ */
+interface CustomCompletion {
+  /** Static list of choices for completion */
+  choices?: string[];
+  /** Shell command to execute for dynamic completion */
+  shellCommand?: string;
+}
+/**
+ * Completion metadata for an argument
+ *
+ * @example
+ * ```ts
+ * // File completion with extension filter
+ * input: arg(z.string(), {
+ *   completion: { type: "file", extensions: ["json", "yaml"] }
+ * })
+ *
+ * // Directory completion
+ * outputDir: arg(z.string(), {
+ *   completion: { type: "directory" }
+ * })
+ *
+ * // Custom static choices
+ * logLevel: arg(z.string(), {
+ *   completion: { custom: { choices: ["debug", "info", "warn", "error"] } }
+ * })
+ *
+ * // Dynamic completion from shell command
+ * branch: arg(z.string(), {
+ *   completion: { custom: { shellCommand: "git branch --format='%(refname:short)'" } }
+ * })
+ *
+ * // File completion with glob pattern matcher
+ * envFile: arg(z.string(), {
+ *   completion: { type: "file", matcher: [".env.*"] }
+ * })
+ * ```
+ */
+type CompletionMeta = {
+  /** Built-in completion type */type?: CompletionType; /** Custom completion (takes precedence over type if both specified) */
+  custom?: CustomCompletion;
+} & ({
+  /** File extension filter (only applies when type is "file") */extensions?: string[];
+  matcher?: never;
+} | {
+  /** Glob patterns for file matching (only applies when type is "file") */matcher?: string[];
+  extensions?: never;
+});
+/**
+ * Context provided to effect callbacks.
+ * When GlobalArgs is extended via declaration merging, `globalArgs` is typed accordingly.
+ */
+type EffectContext = {
+  /** Field name (camelCase) */name: string; /** Validated args for this schema (global args for global effects, command args for command effects) */
+  args: Readonly<Record<string, unknown>>;
+} & (IsEmpty<GlobalArgs> extends true ? {
+  globalArgs?: Readonly<Record<string, unknown>>;
+} : {
+  globalArgs?: Readonly<GlobalArgs>;
+});
+/**
+ * Base metadata shared by all argument types
+ */
+interface BaseArgMeta<TValue = unknown> {
   /** Argument description */
-  description?: string | undefined;
-  /** Whether this is a positional argument */
-  positional: boolean;
+  description?: string;
+  /** Treat as positional argument */
+  positional?: boolean;
   /** Placeholder for help display */
-  placeholder?: string | undefined;
+  placeholder?: string;
   /**
    * Environment variable name(s) to read value from.
-   * If an array, earlier entries take priority.
+   * If an array is provided, earlier entries take priority.
+   * CLI arguments always take precedence over environment variables.
+   *
+   * @example
+   * ```ts
+   * // Single env var
+   * port: arg(z.coerce.number(), { env: "PORT" })
+   *
+   * // Multiple env vars (PORT takes priority over SERVER_PORT)
+   * port: arg(z.coerce.number(), { env: ["PORT", "SERVER_PORT"] })
+   * ```
    */
-  env?: string | string[] | undefined;
-  /** Whether this argument is required */
-  required: boolean;
-  /** Default value if any */
-  defaultValue?: unknown;
-  /** Detected type from schema */
-  type: "string" | "number" | "boolean" | "array" | "unknown";
-  /** Original Zod schema */
-  schema: z.ZodType;
-  /** True if this overrides built-in aliases (-h, -H) */
-  overrideBuiltinAlias?: true;
-  /** Enum values if detected from schema (z.enum) */
-  enumValues?: string[] | undefined;
-  /** Completion metadata from arg() */
-  completion?: CompletionMeta | undefined;
-}
-/**
- * Extracted fields from a schema
- */
-interface ExtractedFields {
-  /** All field definitions */
-  fields: ResolvedFieldMeta[];
-  /** Original schema for validation */
-  schema: ArgsSchema;
-  /** Schema type */
-  schemaType: "object" | "discriminatedUnion" | "union" | "xor" | "intersection";
-  /** Discriminator key (for discriminatedUnion) */
-  discriminator?: string;
-  /** Variants (for discriminatedUnion) */
-  variants?: Array<{
-    discriminatorValue: string;
-    fields: ResolvedFieldMeta[];
-    description?: string;
-  }>;
-  /** Options (for union) */
-  unionOptions?: ExtractedFields[];
-  /** Schema description */
-  description?: string;
+  env?: string | string[];
+  /** Completion configuration for shell tab-completion */
+  completion?: CompletionMeta;
   /**
-   * Unknown keys handling mode
-   * - "strict": Unknown keys cause validation errors (z.strictObject or z.object().strict())
-   * - "strip": Unknown keys trigger warnings (default, z.object())
-   * - "passthrough": Unknown keys are silently ignored (z.looseObject or z.object().passthrough())
+   * Side-effect callback executed after argument parsing and validation.
+   * Runs before the command lifecycle (setup/run/cleanup).
+   * Use Zod .transform() for value transformation instead.
+   *
+   * @example
+   * ```ts
+   * verbose: arg(z.boolean().default(false), {
+   *   alias: "v",
+   *   effect: (value) => {
+   *     if (value) logger.setLevel("debug");
+   *   },
+   * })
+   * ```
    */
-  unknownKeysMode: UnknownKeysMode;
+  effect?: (value: TValue, context: EffectContext) => void | PromiseLike<void>;
 }
 /**
- * Unknown keys handling mode for object schemas
- * - "strict": Unknown keys cause validation errors
- * - "strip": Unknown keys are silently ignored (default)
- * - "passthrough": Unknown keys are passed through
+ * Metadata for regular arguments (non-builtin aliases)
  */
-type UnknownKeysMode = "strict" | "strip" | "passthrough";
+interface RegularArgMeta<TValue = unknown> extends BaseArgMeta<TValue> {
+  /** Short alias (e.g., 'v' for --verbose) */
+  alias?: string;
+}
 /**
- * Detect unknown keys handling mode from a Zod object schema
- *
- * In Zod v4:
- * - Default (strip): _def.catchall is undefined
- * - strict: _def.catchall is ZodNever (type = "never")
- * - passthrough: _def.catchall is ZodUnknown (type = "unknown")
+ * Metadata for overriding built-in aliases (-h, -H)
  */
-declare function getUnknownKeysMode(schema: z.ZodType): UnknownKeysMode;
+interface BuiltinOverrideArgMeta<TValue = unknown> extends BaseArgMeta<TValue> {
+  /** Built-in alias to override ('h' or 'H') */
+  alias: "h" | "H";
+  /** Must be true to override built-in aliases */
+  overrideBuiltinAlias: true;
+}
 /**
- * Convert camelCase to kebab-case
- * @example toKebabCase("dryRun") => "dry-run"
- * @example toKebabCase("outputDir") => "output-dir"
- * @example toKebabCase("XMLParser") => "xml-parser"
+ * Metadata options for argument definition
  */
-declare function toKebabCase(str: string): string;
+type ArgMeta<TValue = unknown> = RegularArgMeta<TValue> | BuiltinOverrideArgMeta<TValue>;
 /**
- * Convert hyphen-separated sequences to camelCase.
+ * Register metadata for a Zod schema
  *
- * Replaces `-x` (hyphen followed by a lowercase letter) with the uppercase
- * variant. Non-hyphenated input (e.g., already camelCase) is returned as-is.
+ * @param schema - The Zod schema
+ * @param meta - Argument metadata
+ * @returns The same schema (for chaining)
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { arg, defineCommand } from "politty";
  *
- * @param str - A string that may contain hyphens
- * @example toCamelCase("dry-run") => "dryRun"
- * @example toCamelCase("output-dir") => "outputDir"
- * @example toCamelCase("dryRun") => "dryRun"
+ * const cmd = defineCommand({
+ *   args: z.object({
+ *     name: arg(z.string(), { description: "User name", positional: true }),
+ *     verbose: arg(z.boolean().default(false), { alias: "v" }),
+ *   }),
+ *   run: (args) => {
+ *     console.log(args.name, args.verbose);
+ *   },
+ * });
+ * ```
  */
-declare function toCamelCase(str: string): string;
 /**
- * Extract all fields from a schema
- *
- * @param schema - The args schema (ZodObject, ZodDiscriminatedUnion, etc.)
- * @returns Extracted field information
+ * Type helper to validate ArgMeta
+ * Forces a type error if alias is "h" or "H" without overrideBuiltinAlias: true
  */
-declare function extractFields(schema: ArgsSchema): ExtractedFields;
+type ValidateArgMeta<M> = M extends {
+  alias: "h" | "H";
+} ? M extends {
+  overrideBuiltinAlias: true;
+} ? M : { [K in keyof M]: M[K] } & {
+  __typeError: "Alias 'h' or 'H' requires overrideBuiltinAlias: true";
+} : M;
+declare function arg<T extends z.ZodType>(schema: T): T;
+declare function arg<T extends z.ZodType, M extends ArgMeta<z.output<T>>>(schema: T, meta: ValidateArgMeta<M>): T;
 //#endregion
-export { LazyCommand as A, RunResult as C, SetupContext as D, RunnableCommand as E, lazy as M, SubCommandValue as O, RunCommandOptions as S, RunResultSuccess as T, LogLevel as _, getUnknownKeysMode as a, MainOptions as b, AnyCommand as c, CollectedLogs as d, Command as f, LogEntry as g, GlobalArgs as h, extractFields as i, isLazyCommand as j, SubCommandsRecord as k, ArgsSchema as l, Example as m, ResolvedFieldMeta as n, toCamelCase as o, CommandBase as p, UnknownKeysMode as r, toKebabCase as s, ExtractedFields as t, CleanupContext as u, LogStream as v, RunResultFailure as w, NonRunnableCommand as x, Logger as y };
-//# sourceMappingURL=schema-extractor-CVf0J4An.d.cts.map
+export { SubCommandValue as A, NonRunnableCommand as C, RunResultSuccess as D, RunResultFailure as E, LazyCommand as M, isLazyCommand as N, RunnableCommand as O, lazy as P, MainOptions as S, RunResult as T, IsEmpty as _, EffectContext as a, LogStream as b, ArgsSchema as c, Command as d, CommandBase as f, GlobalSetupContext as g, GlobalCleanupContext as h, CustomCompletion as i, SubCommandsRecord as j, SetupContext as k, CleanupContext as l, GlobalArgs as m, CompletionMeta as n, arg as o, Example as p, CompletionType as r, AnyCommand as s, ArgMeta as t, CollectedLogs as u, LogEntry as v, RunCommandOptions as w, Logger as x, LogLevel as y };
+//# sourceMappingURL=arg-registry-BDybpyo5.d.cts.map

package/dist/arg-registry-BDybpyo5.d.cts.map

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

package/dist/{schema-extractor-C9APqeSL.d.ts → arg-registry-CHmAzJOM.d.ts}

@@ -1,4 +1,3 @@
-import { n as CompletionMeta } from "./arg-registry-2m40k1Et.js";
 import { z } from "zod";
 
 //#region src/lazy.d.ts
@@ -58,6 +57,10 @@ declare function lazy<T extends AnyCommand>(meta: T, load: () => Promise<AnyComm
  * ```
  */
 interface GlobalArgs {}
+/**
+ * Detect empty interface (used for GlobalArgs declaration merging)
+ */
+type IsEmpty<T> = keyof T extends never ? true : false;
 /**
  * Example definition for a command
  */
@@ -99,6 +102,17 @@ interface CleanupContext<TArgs = unknown> {
   /** Error if command execution failed */
   error?: Error | undefined;
 }
+/**
+ * Context provided to global setup function (runMain/runCommand level)
+ */
+interface GlobalSetupContext {}
+/**
+ * Context provided to global cleanup function (runMain/runCommand level)
+ */
+interface GlobalCleanupContext {
+  /** Error if command execution failed */
+  error?: Error | undefined;
+}
 /**
  * Base command interface (shared properties)
  * @template TArgsSchema - The Zod schema type for arguments
@@ -186,6 +200,10 @@ interface MainOptions {
   logger?: Logger;
   /** Global args schema (shared across all subcommands) */
   globalArgs?: ArgsSchema;
+  /** Global setup hook (runs before command execution) */
+  setup?: ((context: GlobalSetupContext) => void | Promise<void>) | undefined;
+  /** Global cleanup hook (runs after command execution, always executes even on error) */
+  cleanup?: ((context: GlobalCleanupContext) => void | Promise<void>) | undefined;
 }
 /**
  * Options for runCommand (programmatic/test usage)
@@ -201,6 +219,10 @@ interface RunCommandOptions {
   logger?: Logger;
   /** Global args schema (shared across all subcommands) */
   globalArgs?: ArgsSchema;
+  /** Global setup hook (runs before command execution) */
+  setup?: ((context: GlobalSetupContext) => void | Promise<void>) | undefined;
+  /** Global cleanup hook (runs after command execution, always executes even on error) */
+  cleanup?: ((context: GlobalCleanupContext) => void | Promise<void>) | undefined;
 }
 /**
  * Log level type
@@ -265,115 +287,173 @@ interface RunResultFailure {
  */
 type RunResult<T = unknown> = RunResultSuccess<T> | RunResultFailure;
 //#endregion
-//#region src/core/schema-extractor.d.ts
+//#region src/core/arg-registry.d.ts
 /**
- * Resolved metadata for an argument field
+ * Built-in completion types
  */
-interface ResolvedFieldMeta {
-  /** Field name (camelCase, as defined in schema) */
-  name: string;
-  /** CLI option name (kebab-case, for command line usage) */
-  cliName: string;
-  /** Short alias (e.g., 'v' for --verbose) */
-  alias?: string | undefined;
+type CompletionType = "file" | "directory" | "none";
+/**
+ * Custom completion specification
+ */
+interface CustomCompletion {
+  /** Static list of choices for completion */
+  choices?: string[];
+  /** Shell command to execute for dynamic completion */
+  shellCommand?: string;
+}
+/**
+ * Completion metadata for an argument
+ *
+ * @example
+ * ```ts
+ * // File completion with extension filter
+ * input: arg(z.string(), {
+ *   completion: { type: "file", extensions: ["json", "yaml"] }
+ * })
+ *
+ * // Directory completion
+ * outputDir: arg(z.string(), {
+ *   completion: { type: "directory" }
+ * })
+ *
+ * // Custom static choices
+ * logLevel: arg(z.string(), {
+ *   completion: { custom: { choices: ["debug", "info", "warn", "error"] } }
+ * })
+ *
+ * // Dynamic completion from shell command
+ * branch: arg(z.string(), {
+ *   completion: { custom: { shellCommand: "git branch --format='%(refname:short)'" } }
+ * })
+ *
+ * // File completion with glob pattern matcher
+ * envFile: arg(z.string(), {
+ *   completion: { type: "file", matcher: [".env.*"] }
+ * })
+ * ```
+ */
+type CompletionMeta = {
+  /** Built-in completion type */type?: CompletionType; /** Custom completion (takes precedence over type if both specified) */
+  custom?: CustomCompletion;
+} & ({
+  /** File extension filter (only applies when type is "file") */extensions?: string[];
+  matcher?: never;
+} | {
+  /** Glob patterns for file matching (only applies when type is "file") */matcher?: string[];
+  extensions?: never;
+});
+/**
+ * Context provided to effect callbacks.
+ * When GlobalArgs is extended via declaration merging, `globalArgs` is typed accordingly.
+ */
+type EffectContext = {
+  /** Field name (camelCase) */name: string; /** Validated args for this schema (global args for global effects, command args for command effects) */
+  args: Readonly<Record<string, unknown>>;
+} & (IsEmpty<GlobalArgs> extends true ? {
+  globalArgs?: Readonly<Record<string, unknown>>;
+} : {
+  globalArgs?: Readonly<GlobalArgs>;
+});
+/**
+ * Base metadata shared by all argument types
+ */
+interface BaseArgMeta<TValue = unknown> {
   /** Argument description */
-  description?: string | undefined;
-  /** Whether this is a positional argument */
-  positional: boolean;
+  description?: string;
+  /** Treat as positional argument */
+  positional?: boolean;
   /** Placeholder for help display */
-  placeholder?: string | undefined;
+  placeholder?: string;
   /**
    * Environment variable name(s) to read value from.
-   * If an array, earlier entries take priority.
+   * If an array is provided, earlier entries take priority.
+   * CLI arguments always take precedence over environment variables.
+   *
+   * @example
+   * ```ts
+   * // Single env var
+   * port: arg(z.coerce.number(), { env: "PORT" })
+   *
+   * // Multiple env vars (PORT takes priority over SERVER_PORT)
+   * port: arg(z.coerce.number(), { env: ["PORT", "SERVER_PORT"] })
+   * ```
    */
-  env?: string | string[] | undefined;
-  /** Whether this argument is required */
-  required: boolean;
-  /** Default value if any */
-  defaultValue?: unknown;
-  /** Detected type from schema */
-  type: "string" | "number" | "boolean" | "array" | "unknown";
-  /** Original Zod schema */
-  schema: z.ZodType;
-  /** True if this overrides built-in aliases (-h, -H) */
-  overrideBuiltinAlias?: true;
-  /** Enum values if detected from schema (z.enum) */
-  enumValues?: string[] | undefined;
-  /** Completion metadata from arg() */
-  completion?: CompletionMeta | undefined;
-}
-/**
- * Extracted fields from a schema
- */
-interface ExtractedFields {
-  /** All field definitions */
-  fields: ResolvedFieldMeta[];
-  /** Original schema for validation */
-  schema: ArgsSchema;
-  /** Schema type */
-  schemaType: "object" | "discriminatedUnion" | "union" | "xor" | "intersection";
-  /** Discriminator key (for discriminatedUnion) */
-  discriminator?: string;
-  /** Variants (for discriminatedUnion) */
-  variants?: Array<{
-    discriminatorValue: string;
-    fields: ResolvedFieldMeta[];
-    description?: string;
-  }>;
-  /** Options (for union) */
-  unionOptions?: ExtractedFields[];
-  /** Schema description */
-  description?: string;
+  env?: string | string[];
+  /** Completion configuration for shell tab-completion */
+  completion?: CompletionMeta;
   /**
-   * Unknown keys handling mode
-   * - "strict": Unknown keys cause validation errors (z.strictObject or z.object().strict())
-   * - "strip": Unknown keys trigger warnings (default, z.object())
-   * - "passthrough": Unknown keys are silently ignored (z.looseObject or z.object().passthrough())
+   * Side-effect callback executed after argument parsing and validation.
+   * Runs before the command lifecycle (setup/run/cleanup).
+   * Use Zod .transform() for value transformation instead.
+   *
+   * @example
+   * ```ts
+   * verbose: arg(z.boolean().default(false), {
+   *   alias: "v",
+   *   effect: (value) => {
+   *     if (value) logger.setLevel("debug");
+   *   },
+   * })
+   * ```
    */
-  unknownKeysMode: UnknownKeysMode;
+  effect?: (value: TValue, context: EffectContext) => void | PromiseLike<void>;
 }
 /**
- * Unknown keys handling mode for object schemas
- * - "strict": Unknown keys cause validation errors
- * - "strip": Unknown keys are silently ignored (default)
- * - "passthrough": Unknown keys are passed through
+ * Metadata for regular arguments (non-builtin aliases)
  */
-type UnknownKeysMode = "strict" | "strip" | "passthrough";
+interface RegularArgMeta<TValue = unknown> extends BaseArgMeta<TValue> {
+  /** Short alias (e.g., 'v' for --verbose) */
+  alias?: string;
+}
 /**
- * Detect unknown keys handling mode from a Zod object schema
- *
- * In Zod v4:
- * - Default (strip): _def.catchall is undefined
- * - strict: _def.catchall is ZodNever (type = "never")
- * - passthrough: _def.catchall is ZodUnknown (type = "unknown")
+ * Metadata for overriding built-in aliases (-h, -H)
  */
-declare function getUnknownKeysMode(schema: z.ZodType): UnknownKeysMode;
+interface BuiltinOverrideArgMeta<TValue = unknown> extends BaseArgMeta<TValue> {
+  /** Built-in alias to override ('h' or 'H') */
+  alias: "h" | "H";
+  /** Must be true to override built-in aliases */
+  overrideBuiltinAlias: true;
+}
 /**
- * Convert camelCase to kebab-case
- * @example toKebabCase("dryRun") => "dry-run"
- * @example toKebabCase("outputDir") => "output-dir"
- * @example toKebabCase("XMLParser") => "xml-parser"
+ * Metadata options for argument definition
  */
-declare function toKebabCase(str: string): string;
+type ArgMeta<TValue = unknown> = RegularArgMeta<TValue> | BuiltinOverrideArgMeta<TValue>;
 /**
- * Convert hyphen-separated sequences to camelCase.
+ * Register metadata for a Zod schema
  *
- * Replaces `-x` (hyphen followed by a lowercase letter) with the uppercase
- * variant. Non-hyphenated input (e.g., already camelCase) is returned as-is.
+ * @param schema - The Zod schema
+ * @param meta - Argument metadata
+ * @returns The same schema (for chaining)
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { arg, defineCommand } from "politty";
  *
- * @param str - A string that may contain hyphens
- * @example toCamelCase("dry-run") => "dryRun"
- * @example toCamelCase("output-dir") => "outputDir"
- * @example toCamelCase("dryRun") => "dryRun"
+ * const cmd = defineCommand({
+ *   args: z.object({
+ *     name: arg(z.string(), { description: "User name", positional: true }),
+ *     verbose: arg(z.boolean().default(false), { alias: "v" }),
+ *   }),
+ *   run: (args) => {
+ *     console.log(args.name, args.verbose);
+ *   },
+ * });
+ * ```
  */
-declare function toCamelCase(str: string): string;
 /**
- * Extract all fields from a schema
- *
- * @param schema - The args schema (ZodObject, ZodDiscriminatedUnion, etc.)
- * @returns Extracted field information
+ * Type helper to validate ArgMeta
+ * Forces a type error if alias is "h" or "H" without overrideBuiltinAlias: true
  */
-declare function extractFields(schema: ArgsSchema): ExtractedFields;
+type ValidateArgMeta<M> = M extends {
+  alias: "h" | "H";
+} ? M extends {
+  overrideBuiltinAlias: true;
+} ? M : { [K in keyof M]: M[K] } & {
+  __typeError: "Alias 'h' or 'H' requires overrideBuiltinAlias: true";
+} : M;
+declare function arg<T extends z.ZodType>(schema: T): T;
+declare function arg<T extends z.ZodType, M extends ArgMeta<z.output<T>>>(schema: T, meta: ValidateArgMeta<M>): T;
 //#endregion
-export { LazyCommand as A, RunResult as C, SetupContext as D, RunnableCommand as E, lazy as M, SubCommandValue as O, RunCommandOptions as S, RunResultSuccess as T, LogLevel as _, getUnknownKeysMode as a, MainOptions as b, AnyCommand as c, CollectedLogs as d, Command as f, LogEntry as g, GlobalArgs as h, extractFields as i, isLazyCommand as j, SubCommandsRecord as k, ArgsSchema as l, Example as m, ResolvedFieldMeta as n, toCamelCase as o, CommandBase as p, UnknownKeysMode as r, toKebabCase as s, ExtractedFields as t, CleanupContext as u, LogStream as v, RunResultFailure as w, NonRunnableCommand as x, Logger as y };
-//# sourceMappingURL=schema-extractor-C9APqeSL.d.ts.map
+export { SubCommandValue as A, NonRunnableCommand as C, RunResultSuccess as D, RunResultFailure as E, LazyCommand as M, isLazyCommand as N, RunnableCommand as O, lazy as P, MainOptions as S, RunResult as T, IsEmpty as _, EffectContext as a, LogStream as b, ArgsSchema as c, Command as d, CommandBase as f, GlobalSetupContext as g, GlobalCleanupContext as h, CustomCompletion as i, SubCommandsRecord as j, SetupContext as k, CleanupContext as l, GlobalArgs as m, CompletionMeta as n, arg as o, Example as p, CompletionType as r, AnyCommand as s, ArgMeta as t, CollectedLogs as u, LogEntry as v, RunCommandOptions as w, Logger as x, LogLevel as y };
+//# sourceMappingURL=arg-registry-CHmAzJOM.d.ts.map

package/dist/arg-registry-CHmAzJOM.d.ts.map

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