@kjanat/dreamcli 3.0.0-rc.6 → 3.0.0-rc.7

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.
Files changed (88) hide show
  1. package/CHANGELOG.md +49 -1
  2. package/dist/core/cli/dispatch.d.mts +0 -1
  3. package/dist/core/cli/dispatch.mjs +1 -1
  4. package/dist/core/cli/help-links.d.mts +0 -1
  5. package/dist/core/cli/index.d.mts +0 -1
  6. package/dist/core/cli/index.mjs +9 -7
  7. package/dist/core/cli/planner.d.mts +0 -1
  8. package/dist/core/cli/planner.mjs +3 -3
  9. package/dist/core/cli/plugin.d.mts +1 -1
  10. package/dist/core/cli/propagate.d.mts +1 -1
  11. package/dist/core/cli/root-help.d.mts +0 -1
  12. package/dist/core/cli/root-help.mjs +6 -1
  13. package/dist/core/cli/root-surface.d.mts +0 -1
  14. package/dist/core/cli/runtime-preflight.d.mts +5 -1
  15. package/dist/core/cli/runtime-preflight.mjs +2 -1
  16. package/dist/core/completion/index.d.mts +0 -1
  17. package/dist/core/completion/index.mjs +1 -1
  18. package/dist/core/completion/shells/bash.d.mts +0 -1
  19. package/dist/core/completion/shells/bash.mjs +3 -2
  20. package/dist/core/completion/shells/fish.d.mts +0 -1
  21. package/dist/core/completion/shells/fish.mjs +3 -2
  22. package/dist/core/completion/shells/powershell.d.mts +0 -1
  23. package/dist/core/completion/shells/powershell.mjs +2 -1
  24. package/dist/core/completion/shells/shared.d.mts +1 -1
  25. package/dist/core/completion/shells/shared.mjs +5 -0
  26. package/dist/core/completion/shells/zsh.d.mts +0 -1
  27. package/dist/core/completion/shells/zsh.mjs +3 -2
  28. package/dist/core/config/index.d.mts +0 -1
  29. package/dist/core/config/index.mjs +2 -2
  30. package/dist/core/config/package-json.d.mts +0 -1
  31. package/dist/core/execution/index.d.mts +0 -1
  32. package/dist/core/execution/index.mjs +3 -2
  33. package/dist/core/help/ansi.mjs +3 -2
  34. package/dist/core/help/index.d.mts +1 -1
  35. package/dist/core/help/index.mjs +12 -6
  36. package/dist/core/json-schema/index.d.mts +1 -1
  37. package/dist/core/json-schema/index.mjs +25 -7
  38. package/dist/core/output/activity.d.mts +0 -1
  39. package/dist/core/output/contracts.d.mts +0 -1
  40. package/dist/core/output/contracts.mjs +1 -1
  41. package/dist/core/output/index.d.mts +0 -1
  42. package/dist/core/output/index.mjs +1 -1
  43. package/dist/core/output/renderers.d.mts +0 -1
  44. package/dist/core/parse/index.d.mts +1 -1
  45. package/dist/core/parse/index.mjs +75 -9
  46. package/dist/core/prompt/index.d.mts +1 -0
  47. package/dist/core/resolve/args.d.mts +1 -1
  48. package/dist/core/resolve/coerce.d.mts +1 -1
  49. package/dist/core/resolve/coerce.mjs +71 -14
  50. package/dist/core/resolve/contracts.d.mts +6 -1
  51. package/dist/core/resolve/errors.d.mts +0 -1
  52. package/dist/core/resolve/flags.d.mts +7 -2
  53. package/dist/core/resolve/flags.mjs +61 -6
  54. package/dist/core/resolve/index.d.mts +1 -1
  55. package/dist/core/resolve/index.mjs +1 -1
  56. package/dist/core/resolve/property.d.mts +3 -0
  57. package/dist/core/resolve/property.mjs +11 -3
  58. package/dist/core/schema/activity.d.mts +31 -11
  59. package/dist/core/schema/arg.d.mts +1 -2
  60. package/dist/core/schema/command.d.mts +8 -6
  61. package/dist/core/schema/command.mjs +3 -1
  62. package/dist/core/schema/flag.d.mts +337 -10
  63. package/dist/core/schema/flag.mjs +185 -3
  64. package/dist/core/schema/index.d.mts +4 -2
  65. package/dist/core/schema/middleware.d.mts +4 -3
  66. package/dist/core/schema/prompt.d.mts +5 -2
  67. package/dist/core/schema/run.d.mts +9 -1
  68. package/dist/core/schema/string-constraints.d.mts +97 -0
  69. package/dist/core/schema/string-constraints.mjs +69 -0
  70. package/dist/core/schema/value-parsers.d.mts +78 -0
  71. package/dist/core/schema/value-parsers.mjs +142 -0
  72. package/dist/core/schema-dsl/to-json-schema.d.mts +0 -1
  73. package/dist/core/testkit/index.d.mts +0 -31
  74. package/dist/core/testkit/index.mjs +1 -1
  75. package/dist/index.d.mts +5 -2
  76. package/dist/index.mjs +5 -5
  77. package/dist/runtime/adapter.d.mts +22 -1
  78. package/dist/runtime/adapter.mjs +3 -0
  79. package/dist/runtime/auto.d.mts +0 -1
  80. package/dist/runtime/deno.d.mts +15 -5
  81. package/dist/runtime/deno.mjs +9 -0
  82. package/dist/runtime/node.d.mts +2 -2
  83. package/dist/runtime/node.mjs +10 -0
  84. package/dist/runtime.d.mts +1 -0
  85. package/dist/testkit.d.mts +1 -0
  86. package/dist/version.mjs +2 -2
  87. package/dreamcli.schema.json +3 -1
  88. package/package.json +12 -13
@@ -1,4 +1,6 @@
1
1
  import { assertNumberConstraints } from "./number-constraints.mjs";
2
+ import { assertStringConstraints } from "./string-constraints.mjs";
3
+ import { parseBytesValue, parseDateValue, parseDurationValue, parseUrlValue } from "./value-parsers.mjs";
2
4
  //#region src/core/schema/flag.ts
3
5
  /**
4
6
  * Flag schema builder with full type inference.
@@ -87,7 +89,12 @@ function createSchema(kind, overrides) {
87
89
  description: void 0,
88
90
  enumValues: void 0,
89
91
  numberConstraints: void 0,
92
+ stringConstraints: void 0,
90
93
  elementSchema: void 0,
94
+ separator: void 0,
95
+ unique: false,
96
+ pathChecks: void 0,
97
+ valueHint: void 0,
91
98
  prompt: void 0,
92
99
  parseFn: void 0,
93
100
  deprecated: void 0,
@@ -420,14 +427,147 @@ var FlagBuilder = class FlagBuilder {
420
427
  }
421
428
  });
422
429
  }
430
+ /**
431
+ * Reject empty strings. Composes with other string constraints.
432
+ *
433
+ * @param value - Whether to reject empty strings.
434
+ * @defaultValue `true`
435
+ * @returns The builder (for chaining).
436
+ *
437
+ * @example
438
+ * ```ts
439
+ * flag.string().nonEmpty() // rejects '', accepts 'x'
440
+ * ```
441
+ */
442
+ nonEmpty(value = true) {
443
+ return new FlagBuilder({
444
+ ...this.schema,
445
+ stringConstraints: {
446
+ ...this.schema.stringConstraints,
447
+ nonEmpty: value
448
+ }
449
+ });
450
+ }
451
+ /**
452
+ * Set an inclusive minimum length (UTF-16 code units). Composes with other
453
+ * string constraints; a later call overrides an earlier `minLength`.
454
+ *
455
+ * @param value - Inclusive minimum length.
456
+ * @returns The builder (for chaining).
457
+ *
458
+ * @example
459
+ * ```ts
460
+ * flag.string().minLength(3) // rejects 'ab', accepts 'abc'
461
+ * ```
462
+ */
463
+ minLength(value) {
464
+ const stringConstraints = {
465
+ ...this.schema.stringConstraints,
466
+ minLength: value
467
+ };
468
+ assertStringConstraints(stringConstraints);
469
+ return new FlagBuilder({
470
+ ...this.schema,
471
+ stringConstraints
472
+ });
473
+ }
474
+ /**
475
+ * Set an inclusive maximum length (UTF-16 code units). Composes with other
476
+ * string constraints; a later call overrides an earlier `maxLength`.
477
+ *
478
+ * @param value - Inclusive maximum length.
479
+ * @returns The builder (for chaining).
480
+ *
481
+ * @example
482
+ * ```ts
483
+ * flag.string().maxLength(8) // rejects 9+ chars
484
+ * ```
485
+ */
486
+ maxLength(value) {
487
+ const stringConstraints = {
488
+ ...this.schema.stringConstraints,
489
+ maxLength: value
490
+ };
491
+ assertStringConstraints(stringConstraints);
492
+ return new FlagBuilder({
493
+ ...this.schema,
494
+ stringConstraints
495
+ });
496
+ }
497
+ /**
498
+ * Require the value to match a regular expression. Anchor with `^`/`$`
499
+ * for full-string matching. Composes with other string constraints.
500
+ *
501
+ * @param value - Pattern the value must match.
502
+ * @returns The builder (for chaining).
503
+ *
504
+ * @example
505
+ * ```ts
506
+ * flag.string().pattern(/^ghp_/) // rejects 'abc', accepts 'ghp_x'
507
+ * ```
508
+ */
509
+ pattern(value) {
510
+ return new FlagBuilder({
511
+ ...this.schema,
512
+ stringConstraints: {
513
+ ...this.schema.stringConstraints,
514
+ pattern: value
515
+ }
516
+ });
517
+ }
518
+ /**
519
+ * Split each CLI occurrence on a separator before element coercion, so
520
+ * `--tag a,b --tag c` resolves to `['a', 'b', 'c']`. Elements are coerced
521
+ * (and rejected) individually with the element schema's own error format.
522
+ *
523
+ * Env and config string values are split on the same separator (their
524
+ * default split is `','` even without this modifier).
525
+ *
526
+ * @param value - Separator string (e.g. `','`).
527
+ * @returns The builder (for chaining).
528
+ *
529
+ * @example
530
+ * ```ts
531
+ * flag.array(flag.enum(['us', 'eu', 'ap'])).separator(',')
532
+ * // --region us,eu --region ap → ['us', 'eu', 'ap']
533
+ * ```
534
+ */
535
+ separator(value) {
536
+ if (value.length === 0) throw new RangeError("array separator must not be empty");
537
+ return new FlagBuilder({
538
+ ...this.schema,
539
+ separator: value
540
+ });
541
+ }
542
+ /**
543
+ * Deduplicate the resolved array, preserving first-seen order. Applied
544
+ * after all sources resolve, using `SameValueZero` semantics (like `Set`).
545
+ *
546
+ * @param value - Whether to deduplicate.
547
+ * @defaultValue `true`
548
+ * @returns The builder (for chaining).
549
+ *
550
+ * @example
551
+ * ```ts
552
+ * flag.array(flag.string()).separator(',').unique()
553
+ * // --tag a,a --tag a → ['a']
554
+ * ```
555
+ */
556
+ unique(value = true) {
557
+ return new FlagBuilder({
558
+ ...this.schema,
559
+ unique: value
560
+ });
561
+ }
423
562
  };
424
563
  /**
425
564
  * Flag schema factory. Call `flag.<kind>()` to create an immutable
426
565
  * {@link FlagBuilder} with full type inference and safe modifier chaining.
427
566
  */
428
567
  const flag = {
429
- string() {
430
- return new FlagBuilder(createSchema("string"));
568
+ string(constraints) {
569
+ if (constraints !== void 0) assertStringConstraints(constraints);
570
+ return new FlagBuilder(createSchema("string", constraints !== void 0 ? { stringConstraints: constraints } : {}));
431
571
  },
432
572
  number(constraints) {
433
573
  if (constraints !== void 0) assertNumberConstraints(constraints);
@@ -447,7 +587,49 @@ const flag = {
447
587
  },
448
588
  custom(parseFn) {
449
589
  return new FlagBuilder(createSchema("custom", { parseFn }));
590
+ },
591
+ url(options) {
592
+ return new FlagBuilder(createSchema("custom", {
593
+ parseFn: (raw) => parseUrlValue(raw, options),
594
+ valueHint: "url"
595
+ }));
596
+ },
597
+ path(options) {
598
+ return new FlagBuilder(createSchema("string", {
599
+ pathChecks: options?.mustExist === true || options?.type !== void 0 ? {
600
+ mustExist: options.mustExist ?? true,
601
+ type: options.type
602
+ } : void 0,
603
+ valueHint: "path"
604
+ }));
605
+ },
606
+ date(options) {
607
+ return new FlagBuilder(createSchema("custom", {
608
+ parseFn: (raw) => parseDateValue(raw, options),
609
+ valueHint: "date"
610
+ }));
611
+ },
612
+ duration() {
613
+ return new FlagBuilder(createSchema("custom", {
614
+ parseFn: parseDurationValue,
615
+ valueHint: "duration"
616
+ }));
617
+ },
618
+ bytes() {
619
+ return new FlagBuilder(createSchema("custom", {
620
+ parseFn: parseBytesValue,
621
+ valueHint: "size"
622
+ }));
623
+ },
624
+ count() {
625
+ return new FlagBuilder(createSchema("count", {
626
+ presence: "defaulted",
627
+ defaultValue: 0
628
+ }));
629
+ },
630
+ keyValue() {
631
+ return new FlagBuilder(createSchema("keyValue", { valueHint: "key=value" }));
450
632
  }
451
633
  };
452
634
  //#endregion
453
- export { FlagBuilder, createSchema, flag, getFlagAliasNames };
635
+ export { FlagBuilder, createSchema, flag, getFlagAliasNames, normalizeFlagAlias, normalizeFlagAliases };
@@ -2,8 +2,10 @@ import { ActivityEvent, Fallback, ProgressHandle, ProgressOptions, SpinnerHandle
2
2
  import { NumberConstraintViolation, NumberConstraints, describeNumberConstraintViolation, validateNumberConstraints } from "./number-constraints.mjs";
3
3
  import { ARG_KINDS, ARG_PRESENCES, ArgBuilder, ArgConfig, ArgFactory, ArgKind, ArgParseFn, ArgPresence, ArgSchema, InferArg, InferArgs, ResolvedArgValue, WithArgPresence, WithVariadic, arg, createArgSchema } from "./arg.mjs";
4
4
  import { ConfirmPromptConfig, InputPromptConfig, MultiselectPromptConfig, PROMPT_KINDS, PromptConfig, PromptConfigBase, PromptKind, PromptResult, SelectChoice, SelectPromptConfig } from "./prompt.mjs";
5
- import { FLAG_KINDS, FLAG_PRESENCES, FlagAlias, FlagBuilder, FlagConfig, FlagFactory, FlagKind, FlagParseFn, FlagPresence, FlagSchema, FlagSchemaOverrides, InferFlag, InferFlags, ResolvedValue, WithPresence, createSchema, flag } from "./flag.mjs";
5
+ import { StringConstraintViolation, StringConstraints, describeStringConstraintViolation, validateStringConstraints } from "./string-constraints.mjs";
6
+ import { DateFlagOptions, UrlFlagOptions } from "./value-parsers.mjs";
7
+ import { FLAG_KINDS, FLAG_PRESENCES, FlagAlias, FlagBuilder, FlagConfig, FlagFactory, FlagKind, FlagParseFn, FlagPresence, FlagSchema, FlagSchemaOverrides, InferFlag, InferFlags, PathChecks, PathFlagOptions, ResolvedValue, WithPresence, createSchema, flag } from "./flag.mjs";
6
8
  import { ErasedMiddlewareHandler, Middleware, MiddlewareHandler, MiddlewareParams, middleware } from "./middleware.mjs";
7
9
  import { RunOptions, RunResult } from "./run.mjs";
8
10
  import { ActionHandler, ActionParams, AnyCommandBuilder, CommandArgEntry, CommandBuilder, CommandConfig, CommandExample, CommandMeta, CommandSchema, DeriveHandler, DeriveParams, ErasedCommand, ErasedDeriveHandler, ErasedInteractiveResolver, InteractiveParams, InteractiveResolver, InteractiveResult, Out, command, group } from "./command.mjs";
9
- export { ARG_KINDS, ARG_PRESENCES, type ActionHandler, type ActionParams, type ActivityEvent, type AnyCommandBuilder, ArgBuilder, type ArgConfig, type ArgFactory, type ArgKind, type ArgParseFn, type ArgPresence, type ArgSchema, type CommandArgEntry, CommandBuilder, type CommandConfig, type CommandExample, type CommandMeta, type CommandSchema, type ConfirmPromptConfig, type DeriveHandler, type DeriveParams, type ErasedCommand, type ErasedDeriveHandler, type ErasedInteractiveResolver, type ErasedMiddlewareHandler, FLAG_KINDS, FLAG_PRESENCES, type Fallback, type FlagAlias, FlagBuilder, type FlagConfig, type FlagFactory, type FlagKind, type FlagParseFn, type FlagPresence, type FlagSchema, type FlagSchemaOverrides, type InferArg, type InferArgs, type InferFlag, type InferFlags, type InputPromptConfig, type InteractiveParams, type InteractiveResolver, type InteractiveResult, type Middleware, type MiddlewareHandler, type MiddlewareParams, type MultiselectPromptConfig, type NumberConstraintViolation, type NumberConstraints, type Out, PROMPT_KINDS, type ProgressHandle, type ProgressOptions, type PromptConfig, type PromptConfigBase, type PromptKind, type PromptResult, type ResolvedArgValue, type ResolvedValue, type RunOptions, type RunResult, type SelectChoice, type SelectPromptConfig, type SpinnerHandle, type SpinnerOptions, type TableColumn, type TableFormat, type TableOptions, type TableStream, type WithArgPresence, type WithPresence, type WithVariadic, arg, command, createArgSchema, createSchema, describeNumberConstraintViolation, flag, group, middleware, validateNumberConstraints };
11
+ export { ARG_KINDS, ARG_PRESENCES, type ActionHandler, type ActionParams, type ActivityEvent, type AnyCommandBuilder, ArgBuilder, type ArgConfig, type ArgFactory, type ArgKind, type ArgParseFn, type ArgPresence, type ArgSchema, type CommandArgEntry, CommandBuilder, type CommandConfig, type CommandExample, type CommandMeta, type CommandSchema, type ConfirmPromptConfig, type DateFlagOptions, type DeriveHandler, type DeriveParams, type ErasedCommand, type ErasedDeriveHandler, type ErasedInteractiveResolver, type ErasedMiddlewareHandler, FLAG_KINDS, FLAG_PRESENCES, type Fallback, type FlagAlias, FlagBuilder, type FlagConfig, type FlagFactory, type FlagKind, type FlagParseFn, type FlagPresence, type FlagSchema, type FlagSchemaOverrides, type InferArg, type InferArgs, type InferFlag, type InferFlags, type InputPromptConfig, type InteractiveParams, type InteractiveResolver, type InteractiveResult, type Middleware, type MiddlewareHandler, type MiddlewareParams, type MultiselectPromptConfig, type NumberConstraintViolation, type NumberConstraints, type Out, PROMPT_KINDS, type PathChecks, type PathFlagOptions, type ProgressHandle, type ProgressOptions, type PromptConfig, type PromptConfigBase, type PromptKind, type PromptResult, type ResolvedArgValue, type ResolvedValue, type RunOptions, type RunResult, type SelectChoice, type SelectPromptConfig, type SpinnerHandle, type SpinnerOptions, type StringConstraintViolation, type StringConstraints, type TableColumn, type TableFormat, type TableOptions, type TableStream, type UrlFlagOptions, type WithArgPresence, type WithPresence, type WithVariadic, arg, command, createArgSchema, createSchema, describeNumberConstraintViolation, describeStringConstraintViolation, flag, group, middleware, validateNumberConstraints, validateStringConstraints };
@@ -1,5 +1,4 @@
1
1
  import { CommandMeta, Out } from "./command.mjs";
2
-
3
2
  //#region src/core/schema/middleware.d.ts
4
3
  /**
5
4
  * Parameters received by a middleware function at runtime.
@@ -48,7 +47,8 @@ type MiddlewareHandler<Output extends Record<string, unknown>> = (params: {
48
47
  readonly flags: Readonly<Record<string, unknown>>;
49
48
  readonly ctx: Readonly<Record<string, unknown>>;
50
49
  readonly out: Out;
51
- readonly meta: CommandMeta; /** Pass context additions downstream. Must include all `Output` properties. */
50
+ readonly meta: CommandMeta;
51
+ /** Pass context additions downstream. Must include all `Output` properties. */
52
52
  readonly next: (additions: Output) => Promise<void>;
53
53
  }) => void | Promise<void>;
54
54
  /**
@@ -80,7 +80,8 @@ interface MiddlewareImpl {
80
80
  * ```
81
81
  */
82
82
  type Middleware<Output extends Record<string, unknown>> = MiddlewareImpl & {
83
- /** @internal Phantom type brand — compile-time only. */readonly _output: Output;
83
+ /** @internal Phantom type brand — compile-time only. */
84
+ readonly _output: Output;
84
85
  };
85
86
  /**
86
87
  * Create a middleware definition.
@@ -123,10 +123,13 @@ type PromptConfig = ConfirmPromptConfig | InputPromptConfig | SelectPromptConfig
123
123
  * prompt engine's.
124
124
  */
125
125
  type PromptResult = {
126
- /** User provided a value. */readonly answered: true; /** The raw value from the prompt engine (not yet coerced). */
126
+ /** User provided a value. */
127
+ readonly answered: true;
128
+ /** The raw value from the prompt engine (not yet coerced). */
127
129
  readonly value: unknown;
128
130
  } | {
129
- /** User cancelled or aborted (Ctrl+C, ESC, etc.). */readonly answered: false;
131
+ /** User cancelled or aborted (Ctrl+C, ESC, etc.). */
132
+ readonly answered: false;
130
133
  };
131
134
  //#endregion
132
135
  export { type ConfirmPromptConfig, type InputPromptConfig, type MultiselectPromptConfig, PROMPT_KINDS, type PromptConfig, type PromptConfigBase, type PromptKind, type PromptResult, type SelectChoice, type SelectPromptConfig };
@@ -6,7 +6,6 @@ import { CLIPlugin } from "../cli/plugin.mjs";
6
6
  import { CLIError } from "../errors/index.mjs";
7
7
  import { HelpOptions } from "../help/index.mjs";
8
8
  import { CommandMeta, CommandSchema, Out } from "./command.mjs";
9
-
10
9
  //#region src/core/schema/run.d.ts
11
10
  /**
12
11
  * Options accepted by `runCommand()` and internal command execution paths.
@@ -59,6 +58,15 @@ interface RunOptions {
59
58
  * Ignored when an explicit `prompter` is provided.
60
59
  */
61
60
  readonly answers?: readonly TestAnswer[];
61
+ /**
62
+ * Filesystem probe for `flag.path()` checks: reports what exists at a
63
+ * path (`'file'`, `'directory'`, or `null` for nothing).
64
+ *
65
+ * `CLIBuilder.run()` supplies the runtime adapter's probe automatically.
66
+ * When absent (process-free `.execute()` / `runCommand()` without an
67
+ * override), path checks are skipped.
68
+ */
69
+ readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
62
70
  /**
63
71
  * Verbosity level for the output channel.
64
72
  * @defaultValue `'normal'`
@@ -0,0 +1,97 @@
1
+ //#region src/core/schema/string-constraints.d.ts
2
+ /**
3
+ * String constraints for string-valued flags.
4
+ *
5
+ * A single, shared representation and validator so the parse path
6
+ * (`core/parse`) and the resolver coercion path (`core/resolve/coerce`) cannot
7
+ * drift: both import {@link validateStringConstraints} and apply the checks in
8
+ * the same order (nonEmpty → minLength → maxLength → pattern).
9
+ *
10
+ * @module dreamcli/core/schema/string-constraints
11
+ */
12
+ /**
13
+ * Runtime string constraints attached to a string flag/arg schema.
14
+ *
15
+ * Length bounds are **inclusive** and measured in UTF-16 code units
16
+ * (`String.prototype.length`). All fields are optional; an absent field means
17
+ * "no constraint".
18
+ */
19
+ interface StringConstraints {
20
+ /**
21
+ * Reject empty strings (`''`). Whitespace-only strings are still accepted;
22
+ * combine with {@link StringConstraints.pattern | pattern} for stricter rules.
23
+ * @defaultValue `false`
24
+ */
25
+ readonly nonEmpty?: boolean;
26
+ /**
27
+ * Inclusive minimum length. Shorter values are rejected.
28
+ * @defaultValue `undefined` (no minimum)
29
+ */
30
+ readonly minLength?: number;
31
+ /**
32
+ * Inclusive maximum length. Longer values are rejected.
33
+ * @defaultValue `undefined` (no maximum)
34
+ */
35
+ readonly maxLength?: number;
36
+ /**
37
+ * Regular expression the value must match. Tested with
38
+ * `RegExp.prototype.test`; anchor with `^`/`$` for full-string matching.
39
+ * @defaultValue `undefined` (no pattern)
40
+ */
41
+ readonly pattern?: RegExp;
42
+ }
43
+ /**
44
+ * A failed string constraint, discriminated by which rule was violated.
45
+ *
46
+ * `minLength` / `maxLength` carry the offending bound and `pattern` carries
47
+ * the source so callers can render them.
48
+ */
49
+ type StringConstraintViolation = {
50
+ readonly kind: 'nonEmpty';
51
+ } | {
52
+ readonly kind: 'minLength';
53
+ readonly bound: number;
54
+ } | {
55
+ readonly kind: 'maxLength';
56
+ readonly bound: number;
57
+ } | {
58
+ readonly kind: 'pattern';
59
+ readonly pattern: string;
60
+ };
61
+ /**
62
+ * Validate a string value against constraints.
63
+ *
64
+ * The single source of truth for string-constraint checks, shared by the
65
+ * parse and coerce paths. Checks run in a fixed order — **nonEmpty →
66
+ * minLength → maxLength → pattern** — and the first failure is returned.
67
+ * Stateful regexes (`g` / `y` flags) are tested from index 0 every time, so
68
+ * repeated validations cannot flip-flop on `lastIndex`.
69
+ *
70
+ * @param value - The string value to validate.
71
+ * @param constraints - Constraints to enforce, or `undefined` for none.
72
+ * @returns The first {@link StringConstraintViolation}, or `undefined` if valid.
73
+ */
74
+ declare function validateStringConstraints(value: string, constraints: StringConstraints | undefined): StringConstraintViolation | undefined;
75
+ /**
76
+ * Render a terse, human-readable reason for a constraint violation.
77
+ *
78
+ * @param violation - The violation to describe.
79
+ * @returns A message suffix such as `must not be empty` or `must match /^ghp_/`.
80
+ */
81
+ declare function describeStringConstraintViolation(violation: StringConstraintViolation): string;
82
+ /**
83
+ * Assert that a constraints object is well-formed at schema-construction time.
84
+ *
85
+ * Length bounds must be non-negative integers — a fractional or negative
86
+ * length is meaningless (omit the field for "no bound"). An inverted range
87
+ * (`minLength > maxLength`) is also rejected, since it makes the flag/arg
88
+ * permanently unsatisfiable. Throws so the misconfiguration surfaces where
89
+ * the flag/arg is declared, not at parse time.
90
+ *
91
+ * @param constraints - The constraints to validate.
92
+ * @throws RangeError if `minLength` or `maxLength` is negative, fractional, or
93
+ * non-finite, or if `minLength` exceeds `maxLength`.
94
+ */
95
+ declare function assertStringConstraints(constraints: StringConstraints): void;
96
+ //#endregion
97
+ export { type StringConstraintViolation, type StringConstraints, assertStringConstraints, describeStringConstraintViolation, validateStringConstraints };
@@ -0,0 +1,69 @@
1
+ //#region src/core/schema/string-constraints.ts
2
+ /**
3
+ * Validate a string value against constraints.
4
+ *
5
+ * The single source of truth for string-constraint checks, shared by the
6
+ * parse and coerce paths. Checks run in a fixed order — **nonEmpty →
7
+ * minLength → maxLength → pattern** — and the first failure is returned.
8
+ * Stateful regexes (`g` / `y` flags) are tested from index 0 every time, so
9
+ * repeated validations cannot flip-flop on `lastIndex`.
10
+ *
11
+ * @param value - The string value to validate.
12
+ * @param constraints - Constraints to enforce, or `undefined` for none.
13
+ * @returns The first {@link StringConstraintViolation}, or `undefined` if valid.
14
+ */
15
+ function validateStringConstraints(value, constraints) {
16
+ if (constraints === void 0) return;
17
+ if (constraints.nonEmpty === true && value.length === 0) return { kind: "nonEmpty" };
18
+ if (constraints.minLength !== void 0 && value.length < constraints.minLength) return {
19
+ kind: "minLength",
20
+ bound: constraints.minLength
21
+ };
22
+ if (constraints.maxLength !== void 0 && value.length > constraints.maxLength) return {
23
+ kind: "maxLength",
24
+ bound: constraints.maxLength
25
+ };
26
+ if (constraints.pattern !== void 0) {
27
+ constraints.pattern.lastIndex = 0;
28
+ if (!constraints.pattern.test(value)) return {
29
+ kind: "pattern",
30
+ pattern: String(constraints.pattern)
31
+ };
32
+ }
33
+ }
34
+ /**
35
+ * Render a terse, human-readable reason for a constraint violation.
36
+ *
37
+ * @param violation - The violation to describe.
38
+ * @returns A message suffix such as `must not be empty` or `must match /^ghp_/`.
39
+ */
40
+ function describeStringConstraintViolation(violation) {
41
+ switch (violation.kind) {
42
+ case "nonEmpty": return "must not be empty";
43
+ case "minLength": return `must be at least ${violation.bound} characters`;
44
+ case "maxLength": return `must be at most ${violation.bound} characters`;
45
+ case "pattern": return `must match ${violation.pattern}`;
46
+ }
47
+ }
48
+ /**
49
+ * Assert that a constraints object is well-formed at schema-construction time.
50
+ *
51
+ * Length bounds must be non-negative integers — a fractional or negative
52
+ * length is meaningless (omit the field for "no bound"). An inverted range
53
+ * (`minLength > maxLength`) is also rejected, since it makes the flag/arg
54
+ * permanently unsatisfiable. Throws so the misconfiguration surfaces where
55
+ * the flag/arg is declared, not at parse time.
56
+ *
57
+ * @param constraints - The constraints to validate.
58
+ * @throws RangeError if `minLength` or `maxLength` is negative, fractional, or
59
+ * non-finite, or if `minLength` exceeds `maxLength`.
60
+ */
61
+ function assertStringConstraints(constraints) {
62
+ for (const field of ["minLength", "maxLength"]) {
63
+ const bound = constraints[field];
64
+ if (bound !== void 0 && (!Number.isInteger(bound) || bound < 0)) throw new RangeError(`string constraint '${field}' must be a non-negative integer (got ${bound}); omit it for no bound`);
65
+ }
66
+ if (constraints.minLength !== void 0 && constraints.maxLength !== void 0 && constraints.minLength > constraints.maxLength) throw new RangeError(`string constraint 'minLength' (${constraints.minLength}) must not exceed 'maxLength' (${constraints.maxLength})`);
67
+ }
68
+ //#endregion
69
+ export { assertStringConstraints, describeStringConstraintViolation, validateStringConstraints };
@@ -0,0 +1,78 @@
1
+ //#region src/core/schema/value-parsers.d.ts
2
+ /**
3
+ * Parse functions backing the sugar flag factories (`flag.url()`,
4
+ * `flag.date()`, `flag.duration()`, `flag.bytes()`).
5
+ *
6
+ * Each parser converts a raw CLI/env/config value into a typed value and
7
+ * throws a plain `Error` with a human-readable reason on invalid input. The
8
+ * parse and resolve pipelines wrap thrown errors with flag context
9
+ * (`Failed to parse flag --x: <reason>`), so parsers only describe the value
10
+ * problem itself.
11
+ *
12
+ * @module dreamcli/core/schema/value-parsers
13
+ */
14
+ /** Options accepted by `flag.url()`. */
15
+ interface UrlFlagOptions {
16
+ /**
17
+ * Allowed URL protocols, without the trailing colon (e.g. `['https']`).
18
+ * @defaultValue `undefined` (any protocol)
19
+ */
20
+ readonly protocols?: readonly string[];
21
+ }
22
+ /** Options accepted by `flag.date()`. */
23
+ interface DateFlagOptions {
24
+ /**
25
+ * Inclusive earliest allowed date.
26
+ * @defaultValue `undefined` (no lower bound)
27
+ */
28
+ readonly min?: Date;
29
+ /**
30
+ * Inclusive latest allowed date.
31
+ * @defaultValue `undefined` (no upper bound)
32
+ */
33
+ readonly max?: Date;
34
+ }
35
+ /**
36
+ * Parse a strict ISO-8601 date string into a `Date`.
37
+ *
38
+ * Rejects non-string input, non-ISO shapes, and calendar-invalid components
39
+ * (`2026-02-31` does not silently roll over to March). Offset-less datetimes
40
+ * are interpreted as UTC so results never depend on the machine's timezone.
41
+ *
42
+ * @param raw - Raw flag value.
43
+ * @param options - Optional inclusive date bounds.
44
+ * @returns The parsed `Date`.
45
+ * @throws Error with a human-readable reason on invalid input.
46
+ */
47
+ declare function parseDateValue(raw: unknown, options?: DateFlagOptions): Date;
48
+ /**
49
+ * Parse a URL string into a `URL`, optionally restricting protocols.
50
+ *
51
+ * @param raw - Raw flag value.
52
+ * @param options - Optional protocol allowlist.
53
+ * @returns The parsed `URL`.
54
+ * @throws Error with a human-readable reason on invalid input.
55
+ */
56
+ declare function parseUrlValue(raw: unknown, options?: UrlFlagOptions): URL;
57
+ /**
58
+ * Parse a human duration (`'30s'`, `'5m'`, `'1.5h'`, `'250ms'`, `'2d'`) into
59
+ * milliseconds. A bare number (`'1500'`) is treated as milliseconds. Compound
60
+ * values (`'1h30m'`) are supported.
61
+ *
62
+ * @param raw - Raw flag value.
63
+ * @returns Duration in milliseconds.
64
+ * @throws Error with a human-readable reason on invalid input.
65
+ */
66
+ declare function parseDurationValue(raw: unknown): number;
67
+ /**
68
+ * Parse a human byte size (`'512mb'`, `'1.5gb'`, `'64kb'`, `'100b'`) into a
69
+ * byte count. Units are binary (`1kb` = 1024 bytes) and case-insensitive; a
70
+ * bare number is treated as bytes.
71
+ *
72
+ * @param raw - Raw flag value.
73
+ * @returns Size in bytes.
74
+ * @throws Error with a human-readable reason on invalid input.
75
+ */
76
+ declare function parseBytesValue(raw: unknown): number;
77
+ //#endregion
78
+ export { type DateFlagOptions, type UrlFlagOptions, parseBytesValue, parseDateValue, parseDurationValue, parseUrlValue };