@politty/zod 0.2.3 → 0.3.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { $ as toCamelCase, A as LogEntry, B as RunResultFailure, C as Command, D as GlobalCleanupContext, E as GlobalArgs, F as NonRunnableCommand, G as SubCommandsRecord, H as RunnableCommand, I as PromptResolver, J as isLazyCommand, K as UnknownSubcommandHandler, L as RunCommandOptions, M as LogStream, N as Logger, O as GlobalSetupContext, P as MainOptions, Q as UnknownKeysMode, R as RunInvocation, S as CollectedLogs, T as Example, U as SetupContext, V as RunResultSuccess, W as SubCommandValue, X as ExtractedFields, Y as lazy, Z as ResolvedFieldMeta, _ as DynamicCompletionResult, a as CustomCompletion, b as ArgsSchema$1, c as PromptType, d as ExpandCompletion, et as toKebabCase, f as ResolvedExpandCandidate, g as DynamicCompletionResolver, h as DynamicCompletionContext, i as CompletionType, j as LogLevel, k as IsEmpty, l as ValidateArgMeta, m as DynamicCompletionCandidate, n as ArgMeta, nt as SchemaLike, o as EffectContext, p as CompletionDirectiveMask, q as LazyCommand, r as CompletionMeta, s as PromptMeta, t as ArgFn, tt as InferSchemaOutput, u as ExpandCandidate, v as AnyCommand, w as CommandBase, x as CleanupContext, y as ArgSource, z as RunResult } from "./arg-registry-BzQ-y-e0.js";
-import { _ as CompletionResult, g as CompletionOptions, i as GenerateBundledCompletionWorkerResult, n as withCompletionCommand, r as GenerateBundledCompletionWorkerOptions, t as WithCompletionOptions, x as InternalArgsSchema } from "./with-completion-command-CmVdHFHX.js";
+import { $ as toCamelCase, A as LogEntry, B as RunResultFailure, C as Command, D as GlobalCleanupContext, E as GlobalArgs, F as NonRunnableCommand, G as SubCommandsRecord, H as RunnableCommand, I as PromptResolver, J as isLazyCommand, K as UnknownSubcommandHandler, L as RunCommandOptions, M as LogStream, N as Logger, O as GlobalSetupContext, P as MainOptions, Q as UnknownKeysMode, R as RunInvocation, S as CollectedLogs, T as Example, U as SetupContext, V as RunResultSuccess, W as SubCommandValue, X as ExtractedFields, Y as lazy, Z as ResolvedFieldMeta, _ as DynamicCompletionResult, a as CustomCompletion, b as ArgsSchema$1, c as PromptType, d as ExpandCompletion, et as toKebabCase, f as ResolvedExpandCandidate, g as DynamicCompletionResolver, h as DynamicCompletionContext, i as CompletionType, j as LogLevel, k as IsEmpty, l as ValidateArgMeta, m as DynamicCompletionCandidate, n as ArgMeta, nt as SchemaLike, o as EffectContext, p as CompletionDirectiveMask, q as LazyCommand, r as CompletionMeta, s as PromptMeta, t as ArgFn, tt as InferSchemaOutput, u as ExpandCandidate, v as AnyCommand, w as CommandBase, x as CleanupContext, y as ArgSource, z as RunResult } from "./arg-registry-DdEs3jd0.js";
+import { _ as CompletionResult, g as CompletionOptions, i as GenerateBundledCompletionWorkerResult, n as withCompletionCommand, r as GenerateBundledCompletionWorkerOptions, t as WithCompletionOptions, x as InternalArgsSchema } from "./with-completion-command-Bi7v_Wlq.js";
 import { z } from "zod";
 //#region ../core/src/core/schema-extractor.d.ts
 /**
@@ -7,14 +7,14 @@ import { z } from "zod";
  * schema politty itself attaches to a command (including internal
  * descriptor-based commands), not just user-provided library schemas.
  */
-declare function getUnknownKeysMode(schema: ArgsSchema$1): UnknownKeysMode;
+export declare function getUnknownKeysMode(schema: ArgsSchema$1): UnknownKeysMode;
 /**
  * Extract all fields from a schema
  *
  * @param schema - The args schema (ZodObject, ZodDiscriminatedUnion, etc.)
  * @returns Extracted field information
  */
-declare function extractFields(schema: ArgsSchema$1): ExtractedFields;
+export declare function extractFields(schema: ArgsSchema$1): ExtractedFields;
 //#endregion
 //#region ../core/src/adapter/types.d.ts
 /**
@@ -55,7 +55,7 @@ type ValidationResult<T> = {
  *
  * Never returns: it exits the process, like `runMain`.
  */
-declare function runPolittyCli(ownerPackage: string): Promise<never>;
+export declare function runPolittyCli(ownerPackage: string): Promise<never>;
 //#endregion
 //#region ../core/src/compile-cache-shim.d.ts
 /**
@@ -155,7 +155,7 @@ interface GenerateCompileCacheShimResult {
  * a `bin` path still pointing at the real CLI entry fails loudly instead of
  * clobbering the build output.
  */
-declare function createCompileCacheShimGenerator(ownerPackage: string): (options?: GenerateCompileCacheShimOptions) => GenerateCompileCacheShimResult[];
+export declare function createCompileCacheShimGenerator(ownerPackage: string): (options?: GenerateCompileCacheShimOptions) => GenerateCompileCacheShimResult[];
 //#endregion
 //#region ../core/src/core/case-types.d.ts
 /**
@@ -223,7 +223,7 @@ type WithCaseVariants<T> = T extends unknown ? T & { [K in keyof T as CamelCase<
  * - `Object.keys()`, `JSON.stringify()`, and spread return only the original keys.
  * - The `in` operator detects both case variants.
  */
-declare function createDualCaseProxy<T extends Record<string, unknown>>(obj: T): WithCaseVariants<T>;
+export declare function createDualCaseProxy<T extends Record<string, unknown>>(obj: T): WithCaseVariants<T>;
 //#endregion
 //#region ../core/src/core/command.d.ts
 /**
@@ -266,18 +266,26 @@ type WithRunMeta<T> = T & {
  * Resolve merged args from schema and global args type
  */
 type ResolvedArgs<TArgsSchema, TGlobalArgs> = WithRunMeta<MergedArgs<InferArgs<TArgsSchema>, TGlobalArgs>>;
+/**
+ * Resolve the set of subcommand keys usable by `defaultSubCommand`, given the
+ * `subCommands` type inferred from a `defineCommand` call's config literal.
+ * `never` when no `subCommands` were provided, so `defaultSubCommand` cannot
+ * be set on a command without any subcommands.
+ */
+type DefaultSubCommandKey<TSubCommands> = TSubCommands extends SubCommandsRecord ? keyof TSubCommands & string : never;
 /**
  * Config for defining a command
  * @template TArgsSchema - The args schema type (from the CLI's schema library)
  * @template TResult - The return type of run function (void if no run)
  * @template TGlobalArgs - Global args type (from declaration merging or factory)
+ * @template TSubCommands - The `subCommands` record type (inferred from the config literal)
  */
-interface DefineCommandConfig<TArgsSchema extends ArgsSchema$1 | undefined, TResult, TGlobalArgs> {
+interface DefineCommandConfig<TArgsSchema extends ArgsSchema$1 | undefined, TResult, TGlobalArgs, TSubCommands extends SubCommandsRecord | undefined = undefined> {
   name: string;
   description?: string;
   aliases?: string[];
   args?: TArgsSchema;
-  subCommands?: SubCommandsRecord;
+  subCommands?: TSubCommands;
   setup?: (context: {
     args: ResolvedArgs<TArgsSchema, TGlobalArgs>;
   }) => void | Promise<void>;
@@ -298,8 +306,8 @@ interface DefineCommandConfig<TArgsSchema extends ArgsSchema$1 | undefined, TRes
  * level instead of failing at runtime in the registered adapter.
  */
 interface DefineCommandFn<TArgsBase extends ArgsSchema$1 = ArgsSchema$1> {
-  <TArgsSchema extends TArgsBase | undefined = undefined, TResult = void, TGlobalArgs = GlobalArgs>(config: RunnableConfig<TArgsSchema, TResult, TGlobalArgs>): RunnableCommand<TArgsSchema, ResolvedArgs<TArgsSchema, TGlobalArgs>, TResult>;
-  <TArgsSchema extends TArgsBase | undefined = undefined, TGlobalArgs = GlobalArgs>(config: NonRunnableConfig<TArgsSchema, TGlobalArgs>): NonRunnableCommand<TArgsSchema, ResolvedArgs<TArgsSchema, TGlobalArgs>>;
+  <TArgsSchema extends TArgsBase | undefined = undefined, TResult = void, TGlobalArgs = GlobalArgs, TSubCommands extends SubCommandsRecord | undefined = undefined>(config: RunnableConfig<TArgsSchema, TResult, TGlobalArgs, TSubCommands>): RunnableCommand<TArgsSchema, ResolvedArgs<TArgsSchema, TGlobalArgs>, TResult>;
+  <TArgsSchema extends TArgsBase | undefined = undefined, TGlobalArgs = GlobalArgs, TSubCommands extends SubCommandsRecord | undefined = undefined>(config: NonRunnableConfig<TArgsSchema, TGlobalArgs, TSubCommands>): NonRunnableCommand<TArgsSchema, ResolvedArgs<TArgsSchema, TGlobalArgs>>;
 }
 /**
  * `defineCommand` with a pre-bound global args type — the shape returned by
@@ -307,8 +315,8 @@ interface DefineCommandFn<TArgsBase extends ArgsSchema$1 = ArgsSchema$1> {
  * for the same adapter re-pinning as {@link DefineCommandFn}.
  */
 interface BoundDefineCommandFn<TGlobalArgs, TArgsBase extends ArgsSchema$1 = ArgsSchema$1> {
-  <TArgsSchema extends TArgsBase | undefined = undefined, TResult = void>(config: RunnableConfig<TArgsSchema, TResult, TGlobalArgs>): RunnableCommand<TArgsSchema, ResolvedArgs<TArgsSchema, TGlobalArgs>, TResult>;
-  <TArgsSchema extends TArgsBase | undefined = undefined>(config: NonRunnableConfig<TArgsSchema, TGlobalArgs>): NonRunnableCommand<TArgsSchema, ResolvedArgs<TArgsSchema, TGlobalArgs>>;
+  <TArgsSchema extends TArgsBase | undefined = undefined, TResult = void, TSubCommands extends SubCommandsRecord | undefined = undefined>(config: RunnableConfig<TArgsSchema, TResult, TGlobalArgs, TSubCommands>): RunnableCommand<TArgsSchema, ResolvedArgs<TArgsSchema, TGlobalArgs>, TResult>;
+  <TArgsSchema extends TArgsBase | undefined = undefined, TSubCommands extends SubCommandsRecord | undefined = undefined>(config: NonRunnableConfig<TArgsSchema, TGlobalArgs, TSubCommands>): NonRunnableCommand<TArgsSchema, ResolvedArgs<TArgsSchema, TGlobalArgs>>;
 }
 /**
  * The `createDefineCommand` signature, parameterized by the args-schema
@@ -320,14 +328,23 @@ interface CreateDefineCommandFn<TArgsBase extends ArgsSchema$1 = ArgsSchema$1> {
 /**
  * Config with run function (runnable command)
  */
-interface RunnableConfig<TArgsSchema extends ArgsSchema$1 | undefined, TResult, TGlobalArgs> extends DefineCommandConfig<TArgsSchema, TResult, TGlobalArgs> {
+interface RunnableConfig<TArgsSchema extends ArgsSchema$1 | undefined, TResult, TGlobalArgs, TSubCommands extends SubCommandsRecord | undefined = undefined> extends DefineCommandConfig<TArgsSchema, TResult, TGlobalArgs, TSubCommands> {
   run: (args: ResolvedArgs<TArgsSchema, TGlobalArgs>) => TResult;
+  /** Not settable alongside `run` (see `NonRunnableConfig.defaultSubCommand`) */
+  defaultSubCommand?: undefined;
 }
 /**
  * Config without run function (non-runnable command)
  */
-interface NonRunnableConfig<TArgsSchema extends ArgsSchema$1 | undefined, TGlobalArgs> extends Omit<DefineCommandConfig<TArgsSchema, void, TGlobalArgs>, "run"> {
+interface NonRunnableConfig<TArgsSchema extends ArgsSchema$1 | undefined, TGlobalArgs, TSubCommands extends SubCommandsRecord | undefined = undefined> extends Omit<DefineCommandConfig<TArgsSchema, void, TGlobalArgs, TSubCommands>, "run"> {
   run?: undefined;
+  /**
+   * Name of a `subCommands` entry to run when this command is invoked with
+   * no subcommand specified, instead of showing help. Must be a key of
+   * `subCommands` (checked at compile time). See
+   * `NonRunnableCommand.defaultSubCommand`.
+   */
+  defaultSubCommand?: DefaultSubCommandKey<TSubCommands> | undefined;
 }
 //#endregion
 //#region ../core/src/core/runner.d.ts
@@ -357,7 +374,7 @@ interface NonRunnableConfig<TArgsSchema extends ArgsSchema$1 | undefined, TGloba
  * expect(result.exitCode).toBe(0);
  * ```
  */
-declare function runCommand<TResult = unknown>(command: AnyCommand, argv: string[], options?: RunCommandOptions): Promise<RunResult<TResult>>;
+export declare function runCommand<TResult = unknown>(command: AnyCommand, argv: string[], options?: RunCommandOptions): Promise<RunResult<TResult>>;
 /**
  * Run a CLI command as the main entry point
  *
@@ -386,7 +403,7 @@ declare function runCommand<TResult = unknown>(command: AnyCommand, argv: string
  * runMain(command, { version: "1.0.0" });
  * ```
  */
-declare function runMain(command: AnyCommand, options?: MainOptions): Promise<never>;
+export declare function runMain(command: AnyCommand, options?: MainOptions): Promise<never>;
 //#endregion
 //#region ../core/src/output/help-generator.d.ts
 /**
@@ -397,6 +414,8 @@ interface BuiltinOptionDescriptions {
   help?: string;
   /** Description for --help-all option */
   helpAll?: string;
+  /** Description for --help-json option */
+  helpJson?: string;
   /** Description for --version option */
   version?: string;
 }
@@ -428,6 +447,166 @@ interface HelpOptions {
   /** Command hierarchy context */
   context?: CommandContext | undefined;
 }
+/**
+ * Serializable representation of a single argument (positional or option),
+ * whitelisted from {@link ResolvedFieldMeta} down to JSON-safe fields.
+ * `schema`, `completion`, `prompt`, and `effect` are intentionally omitted:
+ * they carry library-specific schema objects and callbacks that cannot
+ * round-trip through JSON, and text help never surfaces them either.
+ */
+interface HelpFieldData {
+  /** Field name (camelCase, as defined in the schema) */
+  name: string;
+  /** CLI option name (kebab-case) */
+  cliName: string;
+  /** Whether this is a positional argument */
+  positional: boolean;
+  /** Whether this argument is required */
+  required: boolean;
+  /** Detected type from schema */
+  type: "string" | "number" | "boolean" | "array" | "unknown";
+  /** Aliases for this option (short: 1 char, long: multi-char) */
+  alias?: string[] | undefined;
+  /** Argument description */
+  description?: string | undefined;
+  /** Placeholder shown in help */
+  placeholder?: string | undefined;
+  /** Environment variable name(s) to read value from */
+  env?: string | string[] | undefined;
+  /** Default value, if any */
+  defaultValue?: unknown;
+  /** Enum values, if detected from schema */
+  enumValues?: string[] | undefined;
+  /** Negation configuration (see {@link ResolvedFieldMeta.negation}) */
+  negation?: string | boolean | undefined;
+  /** Derived negation flag name (no `--` prefix), or undefined when hidden */
+  negationDisplay?: string | undefined;
+  /** Description shown for the negation option */
+  negationDescription?: string | undefined;
+}
+/**
+ * A named group of fields sharing a discriminated-union variant or a plain
+ * union option (see {@link ExtractedFields.variants} / `.unionOptions`).
+ */
+interface HelpVariantData {
+  /** Discriminator value this variant matches (discriminated unions only) */
+  discriminatorValue?: string | undefined;
+  /** Variant/option description */
+  description?: string | undefined;
+  /**
+   * Fields unique to this variant/option (common fields are not repeated
+   * here). Positional fields unique to this variant/option are included too,
+   * duplicated from the flat top-level {@link HelpData.positionals}, so JSON
+   * consumers can attribute a positional to the variant/option it belongs to.
+   */
+  fields: HelpFieldData[];
+}
+/**
+ * Structured usage information, equivalent in content to {@link renderUsageLine}
+ * but free of ANSI styling and rendering order decisions, so JSON consumers
+ * can format it however they like.
+ */
+interface HelpUsageData {
+  /** Command name as shown in usage (includes root name for subcommands) */
+  commandName: string;
+  /** Whether global options are defined */
+  hasGlobalOptions: boolean;
+  /** Whether this command defines any (non-positional) options */
+  hasOptions: boolean;
+  /**
+   * Whether a subcommand token is expected: "required" when the command has
+   * no `run` of its own, "optional" when it does. Undefined when the
+   * command has no (visible) subcommands.
+   */
+  subcommand?: "required" | "optional" | undefined;
+  /** Positional arguments in order */
+  positionals: Array<{
+    name: string;
+    required: boolean;
+  }>;
+}
+/**
+ * A subcommand entry in {@link HelpData.subcommands}.
+ */
+interface HelpSubcommandData {
+  /** Subcommand name (key under `subCommands`) */
+  name: string;
+  /** Subcommand aliases */
+  aliases?: string[] | undefined;
+  /**
+   * Set when this subcommand is a legacy async factory (`() => Promise<Command>`)
+   * registered without {@link lazy}, so no synchronous metadata is available
+   * and `data` cannot be produced. `lazy()` subcommands are always resolved
+   * (their `meta` is synchronous) and never hit this case.
+   */
+  unresolved?: true | undefined;
+  /** Full structured help for this subcommand, recursively. Absent when `unresolved` is true. */
+  data?: HelpData | undefined;
+}
+/**
+ * Structured, JSON-serializable representation of a command's help.
+ * Produced by {@link generateHelpData}; the machine-readable counterpart of
+ * {@link generateHelp}'s formatted text.
+ */
+interface HelpData {
+  /** Command name (command.name) */
+  name: string;
+  /**
+   * Full path from the root command. Empty at the true root; also empty
+   * when generateHelpData is called directly on a non-root command without
+   * a context.commandPath (there is no root to compute the path from).
+   */
+  commandPath: string[];
+  /**
+   * Root command name. Always set when produced through `runMain`/`runCommand`
+   * (equal to `name` itself at the root); `undefined` whenever
+   * `context.rootName` is not supplied to `generateHelpData` -- whether
+   * because no `context` was given at all, or because the given `context`
+   * simply omits `rootName`.
+   */
+  rootName?: string | undefined;
+  /** Root command version, when provided to runMain/runCommand */
+  version?: string | undefined;
+  /** Canonical subcommand name, set only when this command was reached via an alias */
+  aliasFor?: string | undefined;
+  /** Command description */
+  description?: string | undefined;
+  /** Command aliases (as a subcommand) */
+  aliases?: string[] | undefined;
+  /** Structured usage line */
+  usage: HelpUsageData;
+  /** Descriptions of the built-in --help/--help-all/--help-json/--version options */
+  builtinOptions: {
+    help: string;
+    helpAll: string;
+    helpJson: string;
+    version?: string | undefined;
+  };
+  /** Args schema shape: a plain object, or a union/discriminated-union of variants */
+  schemaType?: "object" | "discriminatedUnion" | "union" | "xor" | "intersection" | undefined;
+  /** Positional arguments */
+  positionals: HelpFieldData[];
+  /**
+   * Non-positional options. For `discriminatedUnion`/`union`/`xor` schemas,
+   * this holds only the fields common to every variant/option; the rest are
+   * under `variants`/`unionOptions`.
+   */
+  options: HelpFieldData[];
+  /** Discriminator field name (discriminatedUnion schemas only) */
+  discriminator?: string | undefined;
+  /** Per-variant fields (discriminatedUnion schemas only) */
+  variants?: HelpVariantData[] | undefined;
+  /** Per-option fields (union/xor schemas only) */
+  unionOptions?: HelpVariantData[] | undefined;
+  /** Global options shared across all commands, when a global args schema is defined */
+  globalOptions?: HelpFieldData[] | undefined;
+  /** Subcommands, recursively resolved */
+  subcommands?: HelpSubcommandData[] | undefined;
+  /** Example usages */
+  examples?: Example[] | undefined;
+  /** Additional notes (raw Markdown, unrendered) */
+  notes?: string | undefined;
+}
 /**
  * Generate help text for a command
  *
@@ -435,21 +614,43 @@ interface HelpOptions {
  * @param options - Help generation options
  * @returns Formatted help text
  */
-declare function generateHelp(command: AnyCommand, options: HelpOptions): string;
+export declare function generateHelp(command: AnyCommand, options: HelpOptions): string;
+/**
+ * Options for {@link generateHelpData}
+ */
+interface HelpDataOptions {
+  /** Custom descriptions for the --help/--help-all/--help-json/--version built-in options */
+  descriptions?: BuiltinOptionDescriptions | undefined;
+  /** Command hierarchy context */
+  context?: CommandContext | undefined;
+}
+/**
+ * Generate a structured, JSON-serializable representation of a command's help.
+ *
+ * The machine-readable counterpart of {@link generateHelp}: same underlying
+ * field metadata, but as plain data (no ANSI styling, no fixed layout) and
+ * always including the full recursive subcommand tree (there is no
+ * `--help`/`--help-all` depth distinction here).
+ *
+ * @param command - The command to generate help data for
+ * @param options - Help data generation options
+ * @returns Structured help data
+ */
+export declare function generateHelpData(command: AnyCommand, options?: HelpDataOptions): HelpData;
 //#endregion
 //#region ../core/src/output/logger.d.ts
 /**
  * Enable or disable color output programmatically
  */
-declare function setColorEnabled(enabled: boolean): void;
+export declare function setColorEnabled(enabled: boolean): void;
 /**
  * Check if color output is currently enabled
  */
-declare function isColorEnabled(): boolean;
+export declare function isColorEnabled(): boolean;
 /**
  * Semantic style functions for inline text styling
  */
-declare const styles: {
+export declare const styles: {
   success: (text: string) => string;
   error: (text: string) => string;
   warning: (text: string) => string;
@@ -480,7 +681,7 @@ declare const styles: {
 /**
  * Standardized symbols for CLI output
  */
-declare const symbols: {
+export declare const symbols: {
   success: string;
   error: string;
   warning: string;
@@ -491,7 +692,7 @@ declare const symbols: {
 /**
  * Logger for CLI output
  */
-declare const logger: {
+export declare const logger: {
   /**
    * Log informational message
    */
@@ -540,7 +741,7 @@ declare const logger: {
  *   3. Italic (*text* or _text_)
  *   4. Links [text](url)
  */
-declare function renderInline(text: string): string;
+export declare function renderInline(text: string): string;
 /**
  * Render a Markdown string to styled terminal output.
  *
@@ -549,7 +750,7 @@ declare function renderInline(text: string): string;
  *   - Detects headings, horizontal rules, blockquotes, lists, code blocks, and paragraphs
  *   - Applies inline formatting within each block
  */
-declare function renderMarkdown(markdown: string): string;
+export declare function renderMarkdown(markdown: string): string;
 //#endregion
 //#region ../core/src/parser/argv-parser.d.ts
 /**
@@ -614,43 +815,43 @@ interface ParserOptions {
  * @param options - Parser options
  * @returns Parsed arguments
  */
-declare function parseArgv(argv: string[], options?: ParserOptions): ParsedArgv;
+export declare function parseArgv(argv: string[], options?: ParserOptions): ParsedArgv;
 //#endregion
 //#region ../core/src/validator/args-validator.d.ts
 /**
  * Format validation errors for display
  */
-declare function formatValidationErrors(errors: ValidationError[]): string;
+export declare function formatValidationErrors(errors: ValidationError[]): string;
 //#endregion
 //#region ../core/src/validator/validation-errors.d.ts
 /**
  * Error thrown when positional argument configuration is invalid
  */
-declare class PositionalConfigError extends Error {
+export declare class PositionalConfigError extends Error {
   constructor(message: string);
 }
 /**
  * Error thrown when a reserved alias is used
  */
-declare class ReservedAliasError extends Error {
+export declare class ReservedAliasError extends Error {
   constructor(message: string);
 }
 /**
  * Error thrown when duplicate field names are detected
  */
-declare class DuplicateFieldError extends Error {
+export declare class DuplicateFieldError extends Error {
   constructor(message: string);
 }
 /**
  * Error thrown when duplicate aliases are detected
  */
-declare class DuplicateAliasError extends Error {
+export declare class DuplicateAliasError extends Error {
   constructor(message: string);
 }
 /**
  * Error thrown when fields are case variants of each other (e.g. "my-option" and "myOption")
  */
-declare class CaseVariantCollisionError extends Error {
+export declare class CaseVariantCollisionError extends Error {
   constructor(message: string);
 }
 /**
@@ -658,14 +859,22 @@ declare class CaseVariantCollisionError extends Error {
  * field's name, cliName, alias, or another field's negation (including
  * derived camelCase variants).
  */
-declare class DuplicateNegationError extends Error {
+export declare class DuplicateNegationError extends Error {
   constructor(message: string);
 }
 /**
  * Error thrown when a field name collides with a reserved, framework-injected
  * key on the final args object (e.g. `$source`).
  */
-declare class ReservedFieldNameError extends Error {
+export declare class ReservedFieldNameError extends Error {
+  constructor(message: string);
+}
+/**
+ * Error thrown when a command's `defaultSubCommand` is misconfigured: set
+ * together with `run`, or pointing at a name that isn't a registered
+ * `subCommands` key.
+ */
+export declare class DefaultSubCommandError extends Error {
   constructor(message: string);
 }
 /**
@@ -676,7 +885,7 @@ declare class ReservedFieldNameError extends Error {
  * is rejected at validation time rather than risking a value from one
  * schema silently flowing into the other.
  */
-declare class FieldTypeConflictError extends Error {
+export declare class FieldTypeConflictError extends Error {
   constructor(message: string);
 }
 //#endregion
@@ -688,7 +897,7 @@ interface CommandValidationError {
   /** Path to the command (e.g., ["cli", "build", "watch"]) */
   commandPath: string[];
   /** Error type */
-  type: "duplicate_field" | "duplicate_alias" | "invalid_alias" | "positional_config" | "reserved_alias" | "reserved_field_name" | "case_variant_collision" | "duplicate_negation" | "field_type_conflict" | "subcommand_key_name_mismatch";
+  type: "duplicate_field" | "duplicate_alias" | "invalid_alias" | "positional_config" | "reserved_alias" | "reserved_field_name" | "case_variant_collision" | "duplicate_negation" | "field_type_conflict" | "subcommand_key_name_mismatch" | "default_subcommand_conflict" | "default_subcommand_not_found";
   /** Error message */
   message: string;
   /** Related field name (if applicable) */
@@ -724,7 +933,7 @@ interface ValidateCommandOptions {
  * @param extracted - Extracted fields from schema
  * @throws {DuplicateFieldError} If duplicate field names are found
  */
-declare function validateDuplicateFields(extracted: ExtractedFields): void;
+export declare function validateDuplicateFields(extracted: ExtractedFields): void;
 /**
  * Validate that no duplicate aliases exist
  *
@@ -733,7 +942,7 @@ declare function validateDuplicateFields(extracted: ExtractedFields): void;
  * @param extracted - Extracted fields from schema
  * @throws {DuplicateAliasError} If duplicate aliases are found or alias conflicts with field name
  */
-declare function validateDuplicateAliases(extracted: ExtractedFields): void;
+export declare function validateDuplicateAliases(extracted: ExtractedFields): void;
 /**
  * Validate positional argument configuration
  *
@@ -746,21 +955,25 @@ declare function validateDuplicateAliases(extracted: ExtractedFields): void;
  * @param extracted - Extracted fields from schema
  * @throws {PositionalConfigError} If configuration is invalid
  */
-declare function validatePositionalConfig(extracted: ExtractedFields): void;
+export declare function validatePositionalConfig(extracted: ExtractedFields): void;
 /**
- * Validate that no reserved aliases are used without explicit override
+ * Validate that no reserved names are used without explicit override
  *
- * Reserved aliases:
- * - 'h' is reserved for --help
- * - 'H' is reserved for --help-all
- *
- * Users can override these by setting overrideBuiltinAlias: true
+ * Reserved names:
+ * - 'h' is reserved for --help, 'H' for --help-all (short aliases). Users
+ *   can override this by setting overrideBuiltinAlias: true on the field.
+ * - a field's `cliName` or any long alias matching `help`, `help-all`,
+ *   `help-json`, or `version` collides with the matching built-in long
+ *   flag. This has no override: `overrideBuiltinAlias: true` does not
+ *   suppress it (see {@link checkReservedAliases}).
  *
  * @param extracted - Extracted fields from schema
  * @param _hasSubCommands - Whether the command has subcommands (reserved for future use)
- * @throws {ReservedAliasError} If a reserved alias is used without override flag
+ * @throws {ReservedAliasError} If `h`/`H` is used without `overrideBuiltinAlias: true`,
+ *   or if a field's `cliName`/long alias collides with `help`/`help-all`/`help-json`/`version`
+ *   (this second case is never suppressed by `overrideBuiltinAlias`)
  */
-declare function validateReservedAliases(extracted: ExtractedFields, _hasSubCommands: boolean): void;
+export declare function validateReservedAliases(extracted: ExtractedFields, _hasSubCommands: boolean): void;
 /**
  * Validate that no field name starts with `$`
  *
@@ -776,21 +989,21 @@ declare function validateReservedAliases(extracted: ExtractedFields, _hasSubComm
  * @param extracted - Extracted fields from schema
  * @throws {ReservedFieldNameError} If a field name starts with "$"
  */
-declare function validateReservedFieldNames(extracted: ExtractedFields): void;
+export declare function validateReservedFieldNames(extracted: ExtractedFields): void;
 /**
  * Validate that custom boolean negation names do not collide with anything
  *
  * @param extracted - Extracted fields from schema
  * @throws {DuplicateNegationError} If a colliding negation is found
  */
-declare function validateDuplicateNegations(extracted: ExtractedFields): void;
+export declare function validateDuplicateNegations(extracted: ExtractedFields): void;
 /**
  * Validate that no case-variant collisions exist
  *
  * @param extracted - Extracted fields from schema
  * @throws {CaseVariantCollisionError} If case-variant collisions are found
  */
-declare function validateCaseVariantCollisions(extracted: ExtractedFields): void;
+export declare function validateCaseVariantCollisions(extracted: ExtractedFields): void;
 /**
  * Validate that no cross-schema collisions exist between two schemas
  * (e.g., global args and command args): neither a case-variant collision
@@ -803,7 +1016,15 @@ declare function validateCaseVariantCollisions(extracted: ExtractedFields): void
  * @throws {CaseVariantCollisionError} If cross-schema case-variant collisions are found
  * @throws {FieldTypeConflictError} If a same-named field has a different definition on each schema
  */
-declare function validateCrossSchemaCollisions(extractedA: ExtractedFields, extractedB: ExtractedFields): void;
+export declare function validateCrossSchemaCollisions(extractedA: ExtractedFields, extractedB: ExtractedFields): void;
+/**
+ * Validate that a command's `defaultSubCommand` (if set) is not combined
+ * with `run` and points at a registered `subCommands` key.
+ *
+ * @param command - The command to validate
+ * @throws {DefaultSubCommandError} If the configuration is invalid
+ */
+export declare function validateDefaultSubCommand(command: AnyCommand): void;
 /**
  * Validate a command and all its subcommands recursively
  *
@@ -822,14 +1043,14 @@ declare function validateCrossSchemaCollisions(extractedA: ExtractedFields, extr
  * }
  * ```
  */
-declare function validateCommand(command: AnyCommand, options?: ValidateCommandOptions): Promise<CommandValidationResult>;
+export declare function validateCommand(command: AnyCommand, options?: ValidateCommandOptions): Promise<CommandValidationResult>;
 /**
  * Format command validation errors for display
  *
  * @param errors - Array of validation errors
  * @returns Formatted error message
  */
-declare function formatCommandValidationErrors(errors: CommandValidationError[]): string;
+export declare function formatCommandValidationErrors(errors: CommandValidationError[]): string;
 //#endregion
 //#region src/index.d.ts
 /**
@@ -840,15 +1061,15 @@ declare function formatCommandValidationErrors(errors: CommandValidationError[])
  * the caller's `package.json`: reaching this function means `@politty/zod` is
  * installed, so the shim it writes into your package can resolve it.
  */
-declare const generateCompileCacheShim: (options?: GenerateCompileCacheShimOptions) => GenerateCompileCacheShimResult[];
+export declare const generateCompileCacheShim: (options?: GenerateCompileCacheShimOptions) => GenerateCompileCacheShimResult[];
 /**
  * Supported schema types for args in this package: zod schemas whose
  * output is an object. Narrows `@politty/core`'s Standard-Schema-based
  * `ArgsSchema` back to politty's historical zod-typed public surface.
  */
-type ArgsSchema = z.ZodType<Record<string, any>>;
-declare const defineCommand: DefineCommandFn<ArgsSchema>;
-declare const createDefineCommand: CreateDefineCommandFn<ArgsSchema>;
-declare const arg: ArgFn<z.ZodType>;
+export type ArgsSchema = z.ZodType<Record<string, any>>;
+export declare const defineCommand: DefineCommandFn<ArgsSchema>;
+export declare const createDefineCommand: CreateDefineCommandFn<ArgsSchema>;
+export declare const arg: ArgFn<z.ZodType>;
 //#endregion
-export { type AnyCommand, type ArgFn, type ArgMeta, type ArgSource, ArgsSchema, type BoundDefineCommandFn, type BuiltinOptionDescriptions, type CamelCase, CaseVariantCollisionError, type CleanupContext, type CollectedLogs, type Command, type CommandBase, type CommandContext, type CommandValidationError, type CommandValidationResult, type CompletionDirectiveMask, type CompletionMeta, type CompletionOptions, type CompletionResult, type CompletionType, type CreateDefineCommandFn, type CustomCompletion, type DefineCommandFn, DuplicateAliasError, DuplicateFieldError, DuplicateNegationError, type DynamicCompletionCandidate, type DynamicCompletionContext, type DynamicCompletionResolver, type DynamicCompletionResult, type EffectContext, type Example, type ExpandCandidate, type ExpandCompletion, type ExtractedFields, FieldTypeConflictError, type GenerateBundledCompletionWorkerOptions, type GenerateBundledCompletionWorkerResult, type GenerateCompileCacheShimOptions, type GenerateCompileCacheShimResult, type GlobalArgs, type GlobalCleanupContext, type GlobalSetupContext, type HelpOptions, type InferSchemaOutput, type KebabCase, type LazyCommand, type LogEntry, type LogLevel, type LogStream, type Logger, type MainOptions, type MergedArgs, type NonRunnableCommand, type ParsedArgv, type ParserOptions, PositionalConfigError, type PromptMeta, type PromptResolver, type PromptType, ReservedAliasError, ReservedFieldNameError, type ResolvedExpandCandidate, type ResolvedFieldMeta, type RunCommandOptions, type RunInvocation, type RunResult, type RunResultFailure, type RunResultSuccess, type RunnableCommand, type SchemaLike, type SetupContext, type SubCommandValue, type SubCommandsRecord, type UnknownKeysMode, type UnknownSubcommandHandler, type ValidateArgMeta, type ValidationError, type ValidationResult, type WithCaseVariants, type WithCompletionOptions, arg, createCompileCacheShimGenerator, createDefineCommand, createDualCaseProxy, defineCommand, extractFields, formatCommandValidationErrors, formatValidationErrors, generateCompileCacheShim, generateHelp, getUnknownKeysMode, isColorEnabled, isLazyCommand, lazy, logger, parseArgv, renderInline, renderMarkdown, runCommand, runMain, runPolittyCli, setColorEnabled, styles, symbols, toCamelCase, toKebabCase, validateCaseVariantCollisions, validateCommand, validateCrossSchemaCollisions, validateDuplicateAliases, validateDuplicateFields, validateDuplicateNegations, validatePositionalConfig, validateReservedAliases, validateReservedFieldNames, withCompletionCommand };
+export { type AnyCommand, type ArgFn, type ArgMeta, type ArgSource, type BoundDefineCommandFn, type BuiltinOptionDescriptions, type CamelCase, type CleanupContext, type CollectedLogs, type Command, type CommandBase, type CommandContext, type CommandValidationError, type CommandValidationResult, type CompletionDirectiveMask, type CompletionMeta, type CompletionOptions, type CompletionResult, type CompletionType, type CreateDefineCommandFn, type CustomCompletion, type DefineCommandFn, type DynamicCompletionCandidate, type DynamicCompletionContext, type DynamicCompletionResolver, type DynamicCompletionResult, type EffectContext, type Example, type ExpandCandidate, type ExpandCompletion, type ExtractedFields, type GenerateBundledCompletionWorkerOptions, type GenerateBundledCompletionWorkerResult, type GenerateCompileCacheShimOptions, type GenerateCompileCacheShimResult, type GlobalArgs, type GlobalCleanupContext, type GlobalSetupContext, type HelpData, type HelpDataOptions, type HelpFieldData, type HelpOptions, type HelpSubcommandData, type HelpUsageData, type HelpVariantData, type InferSchemaOutput, type KebabCase, type LazyCommand, type LogEntry, type LogLevel, type LogStream, type Logger, type MainOptions, type MergedArgs, type NonRunnableCommand, type ParsedArgv, type ParserOptions, type PromptMeta, type PromptResolver, type PromptType, type ResolvedExpandCandidate, type ResolvedFieldMeta, type RunCommandOptions, type RunInvocation, type RunResult, type RunResultFailure, type RunResultSuccess, type RunnableCommand, type SchemaLike, type SetupContext, type SubCommandValue, type SubCommandsRecord, type UnknownKeysMode, type UnknownSubcommandHandler, type ValidateArgMeta, type ValidationError, type ValidationResult, type WithCaseVariants, type WithCompletionOptions, isLazyCommand, lazy, toCamelCase, toKebabCase, withCompletionCommand };

package/dist/index.js

@@ -1 +1 @@
-import{i as e,r as t}from"./field-meta-COGya7xp.js";import{t as n}from"./register-C1WbbeYH.js";import{r,t as i}from"./schema-extractor-DU0Vuhbd.js";import{n as a,t as o}from"./cli-main-DYdp1fLi.js";import{n as s,t as c}from"./command-Mbdt0bmN.js";import{C as l,E as u,S as d,T as f,_ as p,a as m,b as h,c as g,d as _,f as v,g as y,h as b,i as x,l as S,m as C,n as w,o as T,p as E,r as D,s as O,t as k,u as A,v as j,w as M,x as N,y as P}from"./runner-BBzVbri9.js";import{o as F,s as I}from"./subcommand-router-D8GTMXYL.js";import{a as L,i as R,n as z,r as B,t as V}from"./logger-CJsyJ8sb.js";import{t as H}from"./with-completion-command-DDohm8U6.js";const U=a(`@politty/zod`),W=s,G=c,K=n;export{y as CaseVariantCollisionError,p as DuplicateAliasError,j as DuplicateFieldError,P as DuplicateNegationError,h as FieldTypeConflictError,N as PositionalConfigError,d as ReservedAliasError,l as ReservedFieldNameError,K as arg,a as createCompileCacheShimGenerator,G as createDefineCommand,D as createDualCaseProxy,W as defineCommand,i as extractFields,T as formatCommandValidationErrors,x as formatValidationErrors,U as generateCompileCacheShim,M as generateHelp,r as getUnknownKeysMode,V as isColorEnabled,F as isLazyCommand,I as lazy,z as logger,m as parseArgv,f as renderInline,u as renderMarkdown,k as runCommand,w as runMain,o as runPolittyCli,B as setColorEnabled,R as styles,L as symbols,t as toCamelCase,e as toKebabCase,O as validateCaseVariantCollisions,g as validateCommand,S as validateCrossSchemaCollisions,A as validateDuplicateAliases,_ as validateDuplicateFields,v as validateDuplicateNegations,E as validatePositionalConfig,C as validateReservedAliases,b as validateReservedFieldNames,H as withCompletionCommand};
+import{a as e,i as t}from"./field-meta-D7G8a7IG.js";import{t as n}from"./register-D0mDOOyc.js";import{r,t as i}from"./schema-extractor-QpSHJvwI.js";import{n as a,t as o}from"./cli-main-q4kY1qaL.js";import{n as s,t as c}from"./command-tLHaJHe6.js";import{C as l,D as u,E as d,O as f,S as p,T as m,_ as h,a as g,b as _,c as v,d as y,f as b,g as x,h as S,i as C,k as w,l as T,m as E,n as D,o as O,p as k,r as A,s as j,t as M,u as N,v as P,w as F,x as I,y as L}from"./runner-bjKUtqk1.js";import{o as R,s as z}from"./subcommand-router-D8GTMXYL.js";import{a as B,i as V,n as H,r as U,t as W}from"./logger-CoeDrmRr.js";import{t as G}from"./with-completion-command-CZ9qcezN.js";const K=a(`@politty/zod`),q=s,J=c,Y=n;export{h as CaseVariantCollisionError,P as DefaultSubCommandError,L as DuplicateAliasError,_ as DuplicateFieldError,I as DuplicateNegationError,p as FieldTypeConflictError,l as PositionalConfigError,F as ReservedAliasError,m as ReservedFieldNameError,Y as arg,a as createCompileCacheShimGenerator,J as createDefineCommand,A as createDualCaseProxy,q as defineCommand,i as extractFields,O as formatCommandValidationErrors,C as formatValidationErrors,K as generateCompileCacheShim,d as generateHelp,u as generateHelpData,r as getUnknownKeysMode,W as isColorEnabled,R as isLazyCommand,z as lazy,H as logger,g as parseArgv,f as renderInline,w as renderMarkdown,M as runCommand,D as runMain,o as runPolittyCli,U as setColorEnabled,V as styles,B as symbols,t as toCamelCase,e as toKebabCase,j as validateCaseVariantCollisions,v as validateCommand,T as validateCrossSchemaCollisions,N as validateDefaultSubCommand,y as validateDuplicateAliases,b as validateDuplicateFields,k as validateDuplicateNegations,E as validatePositionalConfig,S as validateReservedAliases,x as validateReservedFieldNames,G as withCompletionCommand};

package/dist/logger-CoeDrmRr.js

@@ -0,0 +1 @@
+import{styleText as e}from"node:util";function t(){return process.env.NO_COLOR!==void 0||process.env.FORCE_COLOR===`0`||!process.env.FORCE_COLOR&&!(!process.env.CI&&process.stdout.isTTY)}let n=t();function r(e){n=!e}function i(){return!n}function a(...t){return r=>{if(n)return r;let i=r;for(let n of t)i=e(n,i);return i}}const o={success:a(`green`),error:a(`red`),warning:a(`yellow`),info:a(`cyan`),bold:a(`bold`),dim:a(`dim`),italic:a(`italic`),underline:a(`underline`),red:a(`red`),green:a(`green`),yellow:a(`yellow`),blue:a(`blue`),magenta:a(`magenta`),cyan:a(`cyan`),white:a(`white`),gray:a(`gray`),command:a(`bold`),commandName:a(`bold`,`underline`,`cyan`),option:a(`cyan`),optionName:a(`bold`),placeholder:a(`dim`),defaultValue:a(`dim`),required:a(`yellow`),description:e=>e,sectionHeader:a(`bold`,`underline`),version:a(`dim`)},s={success:o.green(`✓`),error:o.red(`✖`),warning:o.yellow(`⚠`),info:o.cyan(`ℹ`),bullet:o.gray(`•`),arrow:o.gray(`→`)},c={info(e){console.log(e)},success(e){console.log(`${s.success} ${o.success(e)}`)},warn(e){console.warn(`${s.warning} ${o.warning(e)}`)},error(e){console.error(`${s.error} ${o.error(e)}`)},log(e){console.log(e)},newline(){console.log(``)},debug(e){console.log(o.dim(e))}};export{s as a,o as i,c as n,r,i as t};