politty 0.11.1 → 0.11.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -139,6 +139,14 @@ const command = defineCommand({
139
139
  });
140
140
  ```
141
141
 
142
+ Use `args.$source(name)` to check whether a value came from an explicit CLI token, an `env` fallback, or neither (e.g. a schema default). It's typed as optional since directly-constructed args objects (e.g. in unit tests) won't have it:
143
+
144
+ ```typescript
145
+ run: (args) => {
146
+ args.$source?.("apiKey"); // "cli" | "env" | "default"
147
+ },
148
+ ```
149
+
142
150
  ### Subcommands
143
151
 
144
152
  Define Git-style subcommands:
@@ -207,6 +207,14 @@ interface GlobalArgs {}
207
207
  * Detect empty interface (used for GlobalArgs declaration merging)
208
208
  */
209
209
  type IsEmpty<T> = keyof T extends never ? true : false;
210
+ /**
211
+ * Where a resolved arg value came from:
212
+ * - `"cli"`: an explicit CLI token (flag or positional)
213
+ * - `"env"`: `field.env` fallback (no CLI token was provided)
214
+ * - `"default"`: neither of the above (e.g. a schema default, or a value
215
+ * resolved by a `prompt` handler)
216
+ */
217
+ type ArgSource = "cli" | "env" | "default";
210
218
  /**
211
219
  * Example definition for a command
212
220
  */
@@ -938,5 +946,5 @@ type ValidateArgMeta<M, TValue = unknown> = M extends {
938
946
  declare function arg<T extends z.ZodType>(schema: T): T;
939
947
  declare function arg<T extends z.ZodType, M extends ArgMeta<z.output<T>>>(schema: T, meta: ValidateArgMeta<M, z.output<T>>): T;
940
948
  //#endregion
941
- export { toKebabCase as $, LogStream as A, SetupContext as B, Example as C, IsEmpty as D, GlobalSetupContext as E, RunCommandOptions as F, isLazyCommand as G, SubCommandsRecord as H, RunResult as I, ResolvedFieldMeta as J, lazy as K, RunResultFailure as L, MainOptions as M, NonRunnableCommand as N, LogEntry as O, PromptResolver as P, toCamelCase as Q, RunResultSuccess as R, CommandBase as S, GlobalCleanupContext as T, UnknownSubcommandHandler as U, SubCommandValue as V, LazyCommand as W, extractFields as X, UnknownKeysMode as Y, getUnknownKeysMode as Z, AnyCommand as _, EffectContext as a, CollectedLogs as b, arg as c, ResolvedExpandCandidate as d, CompletionDirectiveMask as f, DynamicCompletionResult as g, DynamicCompletionResolver as h, CustomCompletion as i, Logger as j, LogLevel as k, ExpandCandidate as l, DynamicCompletionContext as m, CompletionMeta as n, PromptMeta as o, DynamicCompletionCandidate as p, ExtractedFields as q, CompletionType as r, PromptType as s, ArgMeta as t, ExpandCompletion as u, ArgsSchema as v, GlobalArgs as w, Command as x, CleanupContext as y, RunnableCommand as z };
942
- //# sourceMappingURL=arg-registry-aHbip9Hs.d.ts.map
949
+ export { toCamelCase as $, LogLevel as A, RunnableCommand as B, CommandBase as C, GlobalSetupContext as D, GlobalCleanupContext as E, PromptResolver as F, LazyCommand as G, SubCommandValue as H, RunCommandOptions as I, ExtractedFields as J, isLazyCommand as K, RunResult as L, Logger as M, MainOptions as N, IsEmpty as O, NonRunnableCommand as P, getUnknownKeysMode as Q, RunResultFailure as R, Command as S, GlobalArgs as T, SubCommandsRecord as U, SetupContext as V, UnknownSubcommandHandler as W, UnknownKeysMode as X, ResolvedFieldMeta as Y, extractFields as Z, AnyCommand as _, EffectContext as a, CleanupContext as b, arg as c, ResolvedExpandCandidate as d, toKebabCase as et, CompletionDirectiveMask as f, DynamicCompletionResult as g, DynamicCompletionResolver as h, CustomCompletion as i, LogStream as j, LogEntry as k, ExpandCandidate as l, DynamicCompletionContext as m, CompletionMeta as n, PromptMeta as o, DynamicCompletionCandidate as p, lazy as q, CompletionType as r, PromptType as s, ArgMeta as t, ExpandCompletion as u, ArgSource as v, Example as w, CollectedLogs as x, ArgsSchema as y, RunResultSuccess as z };
950
+ //# sourceMappingURL=arg-registry-D558cYkD.d.ts.map
package/dist/augment.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { t as ArgMeta } from "./arg-registry-aHbip9Hs.js";
1
+ import { t as ArgMeta } from "./arg-registry-D558cYkD.js";
2
2
 
3
3
  //#region src/augment.d.ts
4
4
  declare module "zod" {
package/dist/cli.js CHANGED
@@ -1,8 +1,8 @@
1
1
  #!/usr/bin/env node
2
- import { n as runMain } from "./runner-DpsAMVta.js";
3
- import { t as arg } from "./arg-registry-BeLLAW5-.js";
2
+ import { n as runMain } from "./runner-CEDtiI7D.js";
3
+ import { s as arg } from "./schema-extractor-wzJ1cGon.js";
4
4
  import { n as defineCommand } from "./command-B4yA4LXX.js";
5
- import { p as generateBundledCompletionWorker } from "./completion-Rx2DiNBn.js";
5
+ import { p as generateBundledCompletionWorker } from "./completion-B1K87cU5.js";
6
6
  import "./index.js";
7
7
  import { z } from "zod";
8
8
 
@@ -1,3 +1,3 @@
1
- import { f as CompletionDirectiveMask, g as DynamicCompletionResult, h as DynamicCompletionResolver, m as DynamicCompletionContext, p as DynamicCompletionCandidate } from "../arg-registry-aHbip9Hs.js";
2
- import { A as BundledWorkerOptions, C as CandidateResult, D as CompletionContext, E as generateCandidates, F as CompletionMode, I as CompletionOptions, L as CompletionResult, M as CompletableSubcommand, N as CompletionData, O as CompletionType, P as CompletionGenerator, R as ShellType, S as hasCompleteCommand, T as CompletionDirective, _ as extractCompletionData, a as detectShell, b as formatForShell, c as withCompletionCommand, d as GenerateBundledCompletionWorkerOptions, f as GenerateBundledCompletionWorkerResult, g as validateBundledWorkerFile, h as generateBundledCompletionWorker, i as createRefreshCompletionCommand, j as CompletableOption, k as parseCompletionContext, l as ValueCompletionField, m as defaultBundledWorkerOutputPath, n as createCompletionCommand, o as generateCompletion, p as bundledWorkerShellExtension, r as createCompletionWorkerPathCommand, s as getSupportedShells, t as WithCompletionOptions, u as resolveValueCompletion, v as extractPositionals, w as CompletionCandidate, x as createDynamicCompleteCommand, y as ShellFormatOptions } from "../index-dRZSB_t3.js";
1
+ import { f as CompletionDirectiveMask, g as DynamicCompletionResult, h as DynamicCompletionResolver, m as DynamicCompletionContext, p as DynamicCompletionCandidate } from "../arg-registry-D558cYkD.js";
2
+ import { A as BundledWorkerOptions, C as CandidateResult, D as CompletionContext, E as generateCandidates, F as CompletionMode, I as CompletionOptions, L as CompletionResult, M as CompletableSubcommand, N as CompletionData, O as CompletionType, P as CompletionGenerator, R as ShellType, S as hasCompleteCommand, T as CompletionDirective, _ as extractCompletionData, a as detectShell, b as formatForShell, c as withCompletionCommand, d as GenerateBundledCompletionWorkerOptions, f as GenerateBundledCompletionWorkerResult, g as validateBundledWorkerFile, h as generateBundledCompletionWorker, i as createRefreshCompletionCommand, j as CompletableOption, k as parseCompletionContext, l as ValueCompletionField, m as defaultBundledWorkerOutputPath, n as createCompletionCommand, o as generateCompletion, p as bundledWorkerShellExtension, r as createCompletionWorkerPathCommand, s as getSupportedShells, t as WithCompletionOptions, u as resolveValueCompletion, v as extractPositionals, w as CompletionCandidate, x as createDynamicCompleteCommand, y as ShellFormatOptions } from "../index-CeZ1yI46.js";
3
3
  export { type BundledWorkerOptions, type CandidateResult, type CompletableOption, type CompletableSubcommand, type CompletionCandidate, type CompletionContext, type CompletionData, CompletionDirective, type CompletionDirectiveMask, type CompletionGenerator, type CompletionMode, type CompletionOptions, type CompletionResult, type CompletionType, type DynamicCompletionCandidate, type DynamicCompletionContext, type DynamicCompletionResolver, type DynamicCompletionResult, type GenerateBundledCompletionWorkerOptions, type GenerateBundledCompletionWorkerResult, type ShellFormatOptions, type ShellType, type ValueCompletionField, WithCompletionOptions, bundledWorkerShellExtension, createCompletionCommand, createCompletionWorkerPathCommand, createDynamicCompleteCommand, createRefreshCompletionCommand, defaultBundledWorkerOutputPath, detectShell, extractCompletionData, extractPositionals, formatForShell, generateBundledCompletionWorker, generateCandidates, generateCompletion, getSupportedShells, hasCompleteCommand, parseCompletionContext, resolveValueCompletion, validateBundledWorkerFile, withCompletionCommand };
@@ -1,3 +1,3 @@
1
- import { _ as CompletionDirective, a as generateCompletion, b as resolveValueCompletion, c as createDynamicCompleteCommand, d as bundledWorkerShellExtension, f as defaultBundledWorkerOutputPath, g as extractPositionals, h as extractCompletionData, i as detectShell, l as hasCompleteCommand, m as validateBundledWorkerFile, n as createCompletionWorkerPathCommand, o as getSupportedShells, p as generateBundledCompletionWorker, r as createRefreshCompletionCommand, s as withCompletionCommand, t as createCompletionCommand, u as formatForShell, v as generateCandidates, y as parseCompletionContext } from "../completion-Rx2DiNBn.js";
1
+ import { _ as CompletionDirective, a as generateCompletion, b as resolveValueCompletion, c as createDynamicCompleteCommand, d as bundledWorkerShellExtension, f as defaultBundledWorkerOutputPath, g as extractPositionals, h as extractCompletionData, i as detectShell, l as hasCompleteCommand, m as validateBundledWorkerFile, n as createCompletionWorkerPathCommand, o as getSupportedShells, p as generateBundledCompletionWorker, r as createRefreshCompletionCommand, s as withCompletionCommand, t as createCompletionCommand, u as formatForShell, v as generateCandidates, y as parseCompletionContext } from "../completion-B1K87cU5.js";
2
2
 
3
3
  export { CompletionDirective, bundledWorkerShellExtension, createCompletionCommand, createCompletionWorkerPathCommand, createDynamicCompleteCommand, createRefreshCompletionCommand, defaultBundledWorkerOutputPath, detectShell, extractCompletionData, extractPositionals, formatForShell, generateBundledCompletionWorker, generateCandidates, generateCompletion, getSupportedShells, hasCompleteCommand, parseCompletionContext, resolveValueCompletion, validateBundledWorkerFile, withCompletionCommand };
@@ -1,6 +1,6 @@
1
- import { t as arg } from "./arg-registry-BeLLAW5-.js";
1
+ import { a as toCamelCase, n as getAllAliases, s as arg, t as extractFields } from "./schema-extractor-wzJ1cGon.js";
2
2
  import { n as defineCommand } from "./command-B4yA4LXX.js";
3
- import { a as toCamelCase, m as resolveSubCommandMeta, n as getAllAliases, t as extractFields, u as resolveSubCommandAlias } from "./schema-extractor-GEuI_L0X.js";
3
+ import { c as resolveSubCommandMeta, i as resolveSubCommandAlias } from "./subcommand-router-CTzHPGzF.js";
4
4
  import { z } from "zod";
5
5
  import { execFile, execSync, spawn } from "node:child_process";
6
6
  import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
@@ -5606,4 +5606,4 @@ function maybeSpawnRefresh(argv, ctx) {
5606
5606
 
5607
5607
  //#endregion
5608
5608
  export { CompletionDirective as _, generateCompletion as a, resolveValueCompletion as b, createDynamicCompleteCommand as c, bundledWorkerShellExtension as d, defaultBundledWorkerOutputPath as f, extractPositionals as g, extractCompletionData as h, detectShell as i, hasCompleteCommand as l, validateBundledWorkerFile as m, createCompletionWorkerPathCommand as n, getSupportedShells as o, generateBundledCompletionWorker as p, createRefreshCompletionCommand as r, withCompletionCommand as s, createCompletionCommand as t, formatForShell as u, generateCandidates as v, parseCompletionContext as y };
5609
- //# sourceMappingURL=completion-Rx2DiNBn.js.map
5609
+ //# sourceMappingURL=completion-B1K87cU5.js.map
@@ -1,4 +1,4 @@
1
- import { C as Example, J as ResolvedFieldMeta, V as SubCommandValue, _ as AnyCommand, q as ExtractedFields, v as ArgsSchema } from "../arg-registry-aHbip9Hs.js";
1
+ import { H as SubCommandValue, J as ExtractedFields, Y as ResolvedFieldMeta, _ as AnyCommand, w as Example, y as ArgsSchema } from "../arg-registry-D558cYkD.js";
2
2
  import { z } from "zod";
3
3
  import * as fs from "node:fs";
4
4
 
@@ -1,4 +1,5 @@
1
- import { l as resolveLazyCommand, r as getExtractedFields, t as extractFields } from "../schema-extractor-GEuI_L0X.js";
1
+ import { r as getExtractedFields, t as extractFields } from "../schema-extractor-wzJ1cGon.js";
2
+ import { r as resolveLazyCommand } from "../subcommand-router-CTzHPGzF.js";
2
3
  import { t as createLogCollector } from "../log-collector-DK32-73m.js";
3
4
  import { z } from "zod";
4
5
  import * as fs from "node:fs";
@@ -919,7 +920,7 @@ async function executeSingleExample(example, rootCommand, commandPath) {
919
920
  collector.start();
920
921
  let success = true;
921
922
  try {
922
- const { runCommand } = await import("../runner-DpsAMVta.js").then((n) => n.r);
923
+ const { runCommand } = await import("../runner-CEDtiI7D.js").then((n) => n.r);
923
924
  const result = await runCommand(rootCommand, argv);
924
925
  success = result.success;
925
926
  if (!result.success && result.error) console.error(result.error.message);
@@ -1,4 +1,4 @@
1
- import { J as ResolvedFieldMeta, _ as AnyCommand, d as ResolvedExpandCandidate, h as DynamicCompletionResolver, u as ExpandCompletion, v as ArgsSchema, x as Command } from "./arg-registry-aHbip9Hs.js";
1
+ import { S as Command, Y as ResolvedFieldMeta, _ as AnyCommand, d as ResolvedExpandCandidate, h as DynamicCompletionResolver, u as ExpandCompletion, y as ArgsSchema } from "./arg-registry-D558cYkD.js";
2
2
  import { z } from "zod";
3
3
 
4
4
  //#region src/completion/types.d.ts
@@ -659,4 +659,4 @@ interface WithCompletionOptions {
659
659
  declare function withCompletionCommand<T extends AnyCommand>(command: T, options?: string | WithCompletionOptions): T;
660
660
  //#endregion
661
661
  export { BundledWorkerOptions as A, CandidateResult as C, CompletionContext as D, generateCandidates as E, CompletionMode as F, CompletionOptions as I, CompletionResult as L, CompletableSubcommand as M, CompletionData as N, CompletionType as O, CompletionGenerator as P, ShellType as R, hasCompleteCommand as S, CompletionDirective as T, extractCompletionData as _, detectShell as a, formatForShell as b, withCompletionCommand as c, GenerateBundledCompletionWorkerOptions as d, GenerateBundledCompletionWorkerResult as f, validateBundledWorkerFile as g, generateBundledCompletionWorker as h, createRefreshCompletionCommand as i, CompletableOption as j, parseCompletionContext as k, ValueCompletionField as l, defaultBundledWorkerOutputPath as m, createCompletionCommand as n, generateCompletion as o, bundledWorkerShellExtension as p, createCompletionWorkerPathCommand as r, getSupportedShells as s, WithCompletionOptions as t, resolveValueCompletion as u, extractPositionals as v, CompletionCandidate as w, createDynamicCompleteCommand as x, ShellFormatOptions as y };
662
- //# sourceMappingURL=index-dRZSB_t3.d.ts.map
662
+ //# sourceMappingURL=index-CeZ1yI46.d.ts.map
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { $ as toKebabCase, A as LogStream, B as SetupContext, C as Example, D as IsEmpty, E as GlobalSetupContext, F as RunCommandOptions, G as isLazyCommand, H as SubCommandsRecord, I as RunResult, J as ResolvedFieldMeta, K as lazy, L as RunResultFailure, M as MainOptions, N as NonRunnableCommand, O as LogEntry, P as PromptResolver, Q as toCamelCase, R as RunResultSuccess, S as CommandBase, T as GlobalCleanupContext, U as UnknownSubcommandHandler, V as SubCommandValue, W as LazyCommand, X as extractFields, Y as UnknownKeysMode, Z as getUnknownKeysMode, _ as AnyCommand, a as EffectContext, b as CollectedLogs, c as arg, d as ResolvedExpandCandidate, f as CompletionDirectiveMask, g as DynamicCompletionResult, h as DynamicCompletionResolver, i as CustomCompletion, j as Logger, k as LogLevel, l as ExpandCandidate, m as DynamicCompletionContext, n as CompletionMeta, o as PromptMeta, p as DynamicCompletionCandidate, q as ExtractedFields, r as CompletionType, s as PromptType, t as ArgMeta, u as ExpandCompletion, v as ArgsSchema, w as GlobalArgs, x as Command, y as CleanupContext, z as RunnableCommand } from "./arg-registry-aHbip9Hs.js";
2
- import { I as CompletionOptions, L as CompletionResult, c as withCompletionCommand, d as GenerateBundledCompletionWorkerOptions, f as GenerateBundledCompletionWorkerResult, h as generateBundledCompletionWorker, o as generateCompletion, t as WithCompletionOptions } from "./index-dRZSB_t3.js";
1
+ import { $ as toCamelCase, A as LogLevel, B as RunnableCommand, C as CommandBase, D as GlobalSetupContext, E as GlobalCleanupContext, F as PromptResolver, G as LazyCommand, H as SubCommandValue, I as RunCommandOptions, J as ExtractedFields, K as isLazyCommand, L as RunResult, M as Logger, N as MainOptions, O as IsEmpty, P as NonRunnableCommand, Q as getUnknownKeysMode, R as RunResultFailure, S as Command, T as GlobalArgs, U as SubCommandsRecord, V as SetupContext, W as UnknownSubcommandHandler, X as UnknownKeysMode, Y as ResolvedFieldMeta, Z as extractFields, _ as AnyCommand, a as EffectContext, b as CleanupContext, c as arg, d as ResolvedExpandCandidate, et as toKebabCase, f as CompletionDirectiveMask, g as DynamicCompletionResult, h as DynamicCompletionResolver, i as CustomCompletion, j as LogStream, k as LogEntry, l as ExpandCandidate, m as DynamicCompletionContext, n as CompletionMeta, o as PromptMeta, p as DynamicCompletionCandidate, q as lazy, r as CompletionType, s as PromptType, t as ArgMeta, u as ExpandCompletion, v as ArgSource, w as Example, x as CollectedLogs, y as ArgsSchema, z as RunResultSuccess } from "./arg-registry-D558cYkD.js";
2
+ import { I as CompletionOptions, L as CompletionResult, c as withCompletionCommand, d as GenerateBundledCompletionWorkerOptions, f as GenerateBundledCompletionWorkerResult, h as generateBundledCompletionWorker, o as generateCompletion, t as WithCompletionOptions } from "./index-CeZ1yI46.js";
3
3
  import { z } from "zod";
4
4
 
5
5
  //#region src/core/case-types.d.ts
@@ -82,10 +82,26 @@ type InferArgs<TArgsSchema> = TArgsSchema extends z.ZodType ? WithCaseVariants<z
82
82
  * Wraps TGlobalArgs with WithCaseVariants for dual-case access.
83
83
  */
84
84
  type MergedArgs<TLocalArgs, TGlobalArgs> = IsEmpty<TGlobalArgs> extends true ? TLocalArgs : TLocalArgs & WithCaseVariants<TGlobalArgs>;
85
+ /**
86
+ * Add the `$source` helper, which reports whether a given field's final
87
+ * value came from an explicit CLI token, a `field.env` fallback, or
88
+ * neither (schema default / `prompt` resolution).
89
+ *
90
+ * `name` is typed as a plain `string` (not `keyof T`) since the runtime
91
+ * helper deliberately accepts either camelCase or kebab-case field names
92
+ * (matching `createDualCaseProxy`'s dual-case access) and returns
93
+ * `"default"` for anything it doesn't recognize. A `keyof T`-based type
94
+ * would also be unsound for discriminated-union `args` schemas, where
95
+ * narrowing `args` to one branch doesn't retroactively narrow `$source`'s
96
+ * already-fixed parameter type.
97
+ */
98
+ type WithArgSource<T> = T & {
99
+ $source?: (name: string) => ArgSource;
100
+ };
85
101
  /**
86
102
  * Resolve merged args from schema and global args type
87
103
  */
88
- type ResolvedArgs<TArgsSchema, TGlobalArgs> = MergedArgs<InferArgs<TArgsSchema>, TGlobalArgs>;
104
+ type ResolvedArgs<TArgsSchema, TGlobalArgs> = WithArgSource<MergedArgs<InferArgs<TArgsSchema>, TGlobalArgs>>;
89
105
  /**
90
106
  * Config for defining a command
91
107
  * @template TArgsSchema - The Zod schema type for arguments
@@ -526,6 +542,24 @@ declare class CaseVariantCollisionError extends Error {
526
542
  declare class DuplicateNegationError extends Error {
527
543
  constructor(message: string);
528
544
  }
545
+ /**
546
+ * Error thrown when a field name collides with a reserved, framework-injected
547
+ * key on the final args object (e.g. `$source`).
548
+ */
549
+ declare class ReservedFieldNameError extends Error {
550
+ constructor(message: string);
551
+ }
552
+ /**
553
+ * Error thrown when a global field and a same-named local field have
554
+ * different definitions (per `extractFields()`'s type bucket, whether the
555
+ * field is positional, and enum values). Only exactly-matching definitions
556
+ * are allowed to share a name across global/local schemas — anything else
557
+ * is rejected at validation time rather than risking a value from one
558
+ * schema silently flowing into the other.
559
+ */
560
+ declare class FieldTypeConflictError extends Error {
561
+ constructor(message: string);
562
+ }
529
563
  //#endregion
530
564
  //#region src/validator/command-validator.d.ts
531
565
  /**
@@ -535,7 +569,7 @@ interface CommandValidationError {
535
569
  /** Path to the command (e.g., ["cli", "build", "watch"]) */
536
570
  commandPath: string[];
537
571
  /** Error type */
538
- type: "duplicate_field" | "duplicate_alias" | "invalid_alias" | "positional_config" | "reserved_alias" | "case_variant_collision" | "duplicate_negation";
572
+ type: "duplicate_field" | "duplicate_alias" | "invalid_alias" | "positional_config" | "reserved_alias" | "reserved_field_name" | "case_variant_collision" | "duplicate_negation" | "field_type_conflict";
539
573
  /** Error message */
540
574
  message: string;
541
575
  /** Related field name (if applicable) */
@@ -556,6 +590,14 @@ type CommandValidationResult = {
556
590
  interface ValidateCommandOptions {
557
591
  /** Starting command path (for nested validation) */
558
592
  commandPath?: string[];
593
+ /**
594
+ * Global args schema to check the command tree against for cross-schema
595
+ * field collisions (case-variant collisions and `FieldTypeConflictError`
596
+ * conflicts) -- the same check `runCommand()` performs per-invocation at
597
+ * parse time, but here applied eagerly to every command and subcommand
598
+ * regardless of which subcommand path actually gets invoked at runtime.
599
+ */
600
+ globalArgs?: ArgsSchema;
559
601
  }
560
602
  /**
561
603
  * Validate that no duplicate field names exist
@@ -600,6 +642,22 @@ declare function validatePositionalConfig(extracted: ExtractedFields): void;
600
642
  * @throws {ReservedAliasError} If a reserved alias is used without override flag
601
643
  */
602
644
  declare function validateReservedAliases(extracted: ExtractedFields, _hasSubCommands: boolean): void;
645
+ /**
646
+ * Validate that no field name starts with `$`
647
+ *
648
+ * The `$` prefix is reserved for framework-injected helpers on the final
649
+ * args object (e.g. `$source`), and is unusable as a real CLI flag anyway
650
+ * since an unquoted `$name` gets shell-expanded before the program sees it.
651
+ *
652
+ * Checking `field.name` alone is sufficient: aliases can't start with `$`
653
+ * (schema extraction already restricts alias characters to `[A-Za-z0-9-]`),
654
+ * and `cliName` is derived from `name` via `toKebabCase`, which never strips
655
+ * or moves a leading `$`. See {@link checkReservedFieldNames}.
656
+ *
657
+ * @param extracted - Extracted fields from schema
658
+ * @throws {ReservedFieldNameError} If a field name starts with "$"
659
+ */
660
+ declare function validateReservedFieldNames(extracted: ExtractedFields): void;
603
661
  /**
604
662
  * Validate that custom boolean negation names do not collide with anything
605
663
  *
@@ -615,12 +673,16 @@ declare function validateDuplicateNegations(extracted: ExtractedFields): void;
615
673
  */
616
674
  declare function validateCaseVariantCollisions(extracted: ExtractedFields): void;
617
675
  /**
618
- * Validate that no case-variant collisions exist between two schemas
619
- * (e.g., global args and command args).
676
+ * Validate that no cross-schema collisions exist between two schemas
677
+ * (e.g., global args and command args): neither a case-variant collision
678
+ * (same canonical name, different spelling) nor a same-named field with a
679
+ * different definition (same spelling, but the two schemas don't agree on
680
+ * what values are valid).
620
681
  *
621
682
  * @param extractedA - Extracted fields from first schema (e.g., global args)
622
683
  * @param extractedB - Extracted fields from second schema (e.g., command args)
623
684
  * @throws {CaseVariantCollisionError} If cross-schema case-variant collisions are found
685
+ * @throws {FieldTypeConflictError} If a same-named field has a different definition on each schema
624
686
  */
625
687
  declare function validateCrossSchemaCollisions(extractedA: ExtractedFields, extractedB: ExtractedFields): void;
626
688
  /**
@@ -681,5 +743,5 @@ type ValidationResult<T> = {
681
743
  */
682
744
  declare function formatValidationErrors(errors: ValidationError[]): string;
683
745
  //#endregion
684
- export { type AnyCommand, type ArgMeta, type ArgsSchema, 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 CustomCompletion, DuplicateAliasError, DuplicateFieldError, DuplicateNegationError, type DynamicCompletionCandidate, type DynamicCompletionContext, type DynamicCompletionResolver, type DynamicCompletionResult, type EffectContext, type Example, type ExpandCandidate, type ExpandCompletion, type ExtractedFields, type GenerateBundledCompletionWorkerOptions, type GenerateBundledCompletionWorkerResult, type GlobalArgs, type GlobalCleanupContext, type GlobalSetupContext, type HelpOptions, 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, type ResolvedExpandCandidate, type ResolvedFieldMeta, type RunCommandOptions, type RunResult, type RunResultFailure, type RunResultSuccess, type RunnableCommand, type SetupContext, type SubCommandValue, type SubCommandsRecord, type UnknownKeysMode, type UnknownSubcommandHandler, type ValidationError, type ValidationResult, type WithCaseVariants, type WithCompletionOptions, arg, createDefineCommand, createDualCaseProxy, defineCommand, extractFields, formatCommandValidationErrors, formatValidationErrors, generateBundledCompletionWorker, generateCompletion, generateHelp, getUnknownKeysMode, isColorEnabled, isLazyCommand, lazy, logger, parseArgv, renderInline, renderMarkdown, runCommand, runMain, setColorEnabled, styles, symbols, toCamelCase, toKebabCase, validateCaseVariantCollisions, validateCommand, validateCrossSchemaCollisions, validateDuplicateAliases, validateDuplicateFields, validateDuplicateNegations, validatePositionalConfig, validateReservedAliases, withCompletionCommand };
746
+ export { type AnyCommand, type ArgMeta, type ArgSource, type ArgsSchema, 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 CustomCompletion, 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 GlobalArgs, type GlobalCleanupContext, type GlobalSetupContext, type HelpOptions, 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 RunResult, type RunResultFailure, type RunResultSuccess, type RunnableCommand, type SetupContext, type SubCommandValue, type SubCommandsRecord, type UnknownKeysMode, type UnknownSubcommandHandler, type ValidationError, type ValidationResult, type WithCaseVariants, type WithCompletionOptions, arg, createDefineCommand, createDualCaseProxy, defineCommand, extractFields, formatCommandValidationErrors, formatValidationErrors, generateBundledCompletionWorker, generateCompletion, generateHelp, getUnknownKeysMode, isColorEnabled, isLazyCommand, lazy, logger, parseArgv, renderInline, renderMarkdown, runCommand, runMain, setColorEnabled, styles, symbols, toCamelCase, toKebabCase, validateCaseVariantCollisions, validateCommand, validateCrossSchemaCollisions, validateDuplicateAliases, validateDuplicateFields, validateDuplicateNegations, validatePositionalConfig, validateReservedAliases, validateReservedFieldNames, withCompletionCommand };
685
747
  //# sourceMappingURL=index.d.ts.map
package/dist/index.js CHANGED
@@ -1,8 +1,8 @@
1
- import { C as renderMarkdown, S as renderInline, _ as DuplicateFieldError, a as parseArgv, b as ReservedAliasError, c as validateCommand, d as validateDuplicateFields, f as validateDuplicateNegations, g as DuplicateAliasError, h as CaseVariantCollisionError, i as formatValidationErrors, l as validateCrossSchemaCollisions, m as validateReservedAliases, n as runMain, o as formatCommandValidationErrors, p as validatePositionalConfig, s as validateCaseVariantCollisions, t as runCommand, u as validateDuplicateAliases, v as DuplicateNegationError, w as createDualCaseProxy, x as generateHelp, y as PositionalConfigError } from "./runner-DpsAMVta.js";
2
- import { t as arg } from "./arg-registry-BeLLAW5-.js";
1
+ import { C as ReservedFieldNameError, D as createDualCaseProxy, E as renderMarkdown, S as ReservedAliasError, T as renderInline, _ as DuplicateAliasError, a as parseArgv, b as FieldTypeConflictError, c as validateCommand, d as validateDuplicateFields, f as validateDuplicateNegations, g as CaseVariantCollisionError, h as validateReservedFieldNames, i as formatValidationErrors, l as validateCrossSchemaCollisions, m as validateReservedAliases, n as runMain, o as formatCommandValidationErrors, p as validatePositionalConfig, s as validateCaseVariantCollisions, t as runCommand, u as validateDuplicateAliases, v as DuplicateFieldError, w as generateHelp, x as PositionalConfigError, y as DuplicateNegationError } from "./runner-CEDtiI7D.js";
2
+ import { a as toCamelCase, i as getUnknownKeysMode, o as toKebabCase, s as arg, t as extractFields } from "./schema-extractor-wzJ1cGon.js";
3
3
  import { n as defineCommand, t as createDefineCommand } from "./command-B4yA4LXX.js";
4
- import { a as toCamelCase, f as isLazyCommand, i as getUnknownKeysMode, o as toKebabCase, p as lazy, t as extractFields } from "./schema-extractor-GEuI_L0X.js";
5
- import { a as generateCompletion, p as generateBundledCompletionWorker, s as withCompletionCommand } from "./completion-Rx2DiNBn.js";
4
+ import { o as isLazyCommand, s as lazy } from "./subcommand-router-CTzHPGzF.js";
5
+ import { a as generateCompletion, p as generateBundledCompletionWorker, s as withCompletionCommand } from "./completion-B1K87cU5.js";
6
6
  import { a as symbols, i as styles, n as logger, r as setColorEnabled, t as isColorEnabled } from "./logger-DbDkjdfO.js";
7
7
 
8
- export { CaseVariantCollisionError, DuplicateAliasError, DuplicateFieldError, DuplicateNegationError, PositionalConfigError, ReservedAliasError, arg, createDefineCommand, createDualCaseProxy, defineCommand, extractFields, formatCommandValidationErrors, formatValidationErrors, generateBundledCompletionWorker, generateCompletion, generateHelp, getUnknownKeysMode, isColorEnabled, isLazyCommand, lazy, logger, parseArgv, renderInline, renderMarkdown, runCommand, runMain, setColorEnabled, styles, symbols, toCamelCase, toKebabCase, validateCaseVariantCollisions, validateCommand, validateCrossSchemaCollisions, validateDuplicateAliases, validateDuplicateFields, validateDuplicateNegations, validatePositionalConfig, validateReservedAliases, withCompletionCommand };
8
+ export { CaseVariantCollisionError, DuplicateAliasError, DuplicateFieldError, DuplicateNegationError, FieldTypeConflictError, PositionalConfigError, ReservedAliasError, ReservedFieldNameError, arg, createDefineCommand, createDualCaseProxy, defineCommand, extractFields, formatCommandValidationErrors, formatValidationErrors, generateBundledCompletionWorker, generateCompletion, generateHelp, getUnknownKeysMode, isColorEnabled, isLazyCommand, lazy, logger, parseArgv, renderInline, renderMarkdown, runCommand, runMain, setColorEnabled, styles, symbols, toCamelCase, toKebabCase, validateCaseVariantCollisions, validateCommand, validateCrossSchemaCollisions, validateDuplicateAliases, validateDuplicateFields, validateDuplicateNegations, validatePositionalConfig, validateReservedAliases, validateReservedFieldNames, withCompletionCommand };
@@ -1,4 +1,4 @@
1
- import { P as PromptResolver } from "../../arg-registry-aHbip9Hs.js";
1
+ import { F as PromptResolver } from "../../arg-registry-D558cYkD.js";
2
2
 
3
3
  //#region src/prompt/clack/index.d.ts
4
4
  /**
@@ -1,4 +1,4 @@
1
- import { J as ResolvedFieldMeta, q as ExtractedFields } from "../arg-registry-aHbip9Hs.js";
1
+ import { J as ExtractedFields, Y as ResolvedFieldMeta } from "../arg-registry-D558cYkD.js";
2
2
 
3
3
  //#region src/prompt/types.d.ts
4
4
  /**
@@ -1,4 +1,4 @@
1
- import { P as PromptResolver } from "../../arg-registry-aHbip9Hs.js";
1
+ import { F as PromptResolver } from "../../arg-registry-D558cYkD.js";
2
2
 
3
3
  //#region src/prompt/inquirer/index.d.ts
4
4
  /**