@kjanat/dreamcli 3.0.1 → 4.0.0-rc.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.
Files changed (137) hide show
  1. package/CHANGELOG.md +962 -1
  2. package/README.md +7 -3
  3. package/dist/core/cli/builtins.d.mts +47 -0
  4. package/dist/core/cli/builtins.mjs +135 -0
  5. package/dist/core/cli/compiled.d.mts +29 -0
  6. package/dist/core/cli/compiled.mjs +76 -0
  7. package/dist/core/cli/dispatch.d.mts +9 -85
  8. package/dist/core/cli/help-links.d.mts +2 -14
  9. package/dist/core/cli/index.d.mts +282 -101
  10. package/dist/core/cli/index.mjs +497 -264
  11. package/dist/core/cli/planner.d.mts +13 -86
  12. package/dist/core/cli/planner.mjs +47 -30
  13. package/dist/core/cli/plugin.d.mts +1 -1
  14. package/dist/core/cli/propagate.mjs +1 -1
  15. package/dist/core/cli/reserved-flags.d.mts +1 -0
  16. package/dist/core/cli/reserved-flags.mjs +158 -0
  17. package/dist/core/cli/root-help.d.mts +1 -47
  18. package/dist/core/cli/root-help.mjs +37 -47
  19. package/dist/core/cli/root-output-flags.d.mts +1 -0
  20. package/dist/core/cli/root-output-flags.mjs +169 -0
  21. package/dist/core/cli/root-surface.d.mts +1 -68
  22. package/dist/core/cli/root-surface.mjs +2 -2
  23. package/dist/core/cli/runtime-preflight.d.mts +1 -199
  24. package/dist/core/cli/runtime-preflight.mjs +67 -17
  25. package/dist/core/completion/index.d.mts +2 -2
  26. package/dist/core/completion/shells/bash.d.mts +0 -1
  27. package/dist/core/completion/shells/bash.mjs +2 -1
  28. package/dist/core/completion/shells/fish.d.mts +0 -1
  29. package/dist/core/completion/shells/fish.mjs +2 -1
  30. package/dist/core/completion/shells/powershell.d.mts +0 -1
  31. package/dist/core/completion/shells/powershell.mjs +2 -1
  32. package/dist/core/completion/shells/shared.d.mts +3 -114
  33. package/dist/core/completion/shells/shared.mjs +9 -39
  34. package/dist/core/completion/shells/zsh.d.mts +0 -1
  35. package/dist/core/completion/shells/zsh.mjs +2 -1
  36. package/dist/core/config/index.d.mts +3 -3
  37. package/dist/core/config/index.mjs +2 -2
  38. package/dist/core/config/package-json.d.mts +2 -33
  39. package/dist/core/config/package-json.mjs +1 -34
  40. package/dist/core/errors/index.d.mts +7 -7
  41. package/dist/core/execution/index.d.mts +1 -48
  42. package/dist/core/execution/index.mjs +42 -27
  43. package/dist/core/help/ansi.d.mts +0 -11
  44. package/dist/core/help/index.d.mts +3 -35
  45. package/dist/core/help/index.mjs +29 -6
  46. package/dist/core/help/theme.d.mts +1 -21
  47. package/dist/core/json-schema/index.d.mts +279 -10
  48. package/dist/core/json-schema/index.mjs +482 -237
  49. package/dist/core/json-schema/meta-descriptions.generated.d.mts +79 -7
  50. package/dist/core/json-schema/meta-descriptions.generated.mjs +40 -6
  51. package/dist/core/output/activity.d.mts +1 -193
  52. package/dist/core/output/activity.mjs +1 -1
  53. package/dist/core/output/bind.d.mts +1 -37
  54. package/dist/core/output/contracts.d.mts +7 -13
  55. package/dist/core/output/contracts.mjs +1 -1
  56. package/dist/core/output/display-value.d.mts +1 -19
  57. package/dist/core/output/index.d.mts +5 -187
  58. package/dist/core/output/index.mjs +44 -9
  59. package/dist/core/output/renderers.d.mts +1 -45
  60. package/dist/core/output/writer.d.mts +0 -1
  61. package/dist/core/parse/index.d.mts +27 -5
  62. package/dist/core/parse/index.mjs +350 -227
  63. package/dist/core/parse/occurrences.d.mts +89 -0
  64. package/dist/core/parse/occurrences.mjs +114 -0
  65. package/dist/core/prompt/index.d.mts +3 -3
  66. package/dist/core/read-flags/index.d.mts +150 -0
  67. package/dist/core/read-flags/index.mjs +217 -0
  68. package/dist/core/resolve/args.d.mts +35 -4
  69. package/dist/core/resolve/args.mjs +132 -55
  70. package/dist/core/resolve/coerce.d.mts +66 -9
  71. package/dist/core/resolve/coerce.mjs +834 -270
  72. package/dist/core/resolve/config.d.mts +1 -10
  73. package/dist/core/resolve/contracts.d.mts +67 -44
  74. package/dist/core/resolve/errors.mjs +29 -21
  75. package/dist/core/resolve/flags.d.mts +36 -9
  76. package/dist/core/resolve/flags.mjs +129 -151
  77. package/dist/core/resolve/index.d.mts +8 -6
  78. package/dist/core/resolve/index.mjs +51 -18
  79. package/dist/core/resolve/path-checks.d.mts +47 -0
  80. package/dist/core/resolve/path-checks.mjs +102 -0
  81. package/dist/core/resolve/redaction.d.mts +12 -0
  82. package/dist/core/resolve/redaction.mjs +14 -0
  83. package/dist/core/resolve/stages.d.mts +85 -0
  84. package/dist/core/resolve/stages.mjs +170 -0
  85. package/dist/core/resolve/standard.d.mts +1 -24
  86. package/dist/core/resolve/standard.mjs +141 -43
  87. package/dist/core/schema/activity.d.mts +16 -16
  88. package/dist/core/schema/arg.d.mts +849 -71
  89. package/dist/core/schema/arg.mjs +727 -54
  90. package/dist/core/schema/brand.d.mts +17 -0
  91. package/dist/core/schema/cardinality.d.mts +301 -0
  92. package/dist/core/schema/cardinality.mjs +514 -0
  93. package/dist/core/schema/command.d.mts +173 -119
  94. package/dist/core/schema/command.mjs +305 -42
  95. package/dist/core/schema/flag.d.mts +515 -173
  96. package/dist/core/schema/flag.mjs +576 -78
  97. package/dist/core/schema/index.d.mts +11 -8
  98. package/dist/core/schema/index.mjs +10 -0
  99. package/dist/core/schema/middleware.d.mts +15 -12
  100. package/dist/core/schema/number-constraints.d.mts +5 -5
  101. package/dist/core/schema/prompt.d.mts +4 -4
  102. package/dist/core/schema/provenance.d.mts +99 -0
  103. package/dist/core/schema/provenance.mjs +28 -0
  104. package/dist/core/schema/run.d.mts +21 -60
  105. package/dist/core/schema/source.d.mts +179 -0
  106. package/dist/core/schema/source.mjs +206 -0
  107. package/dist/core/schema/standard.d.mts +12 -19
  108. package/dist/core/schema/stdin.d.mts +87 -0
  109. package/dist/core/schema/stdin.mjs +91 -0
  110. package/dist/core/schema/string-constraints.d.mts +16 -5
  111. package/dist/core/schema/string-constraints.mjs +18 -1
  112. package/dist/core/schema/value-parsers.d.mts +81 -9
  113. package/dist/core/schema/value-parsers.mjs +19 -1
  114. package/dist/core/schema/value.d.mts +242 -0
  115. package/dist/core/schema/value.mjs +573 -0
  116. package/dist/core/testkit/index.d.mts +30 -3
  117. package/dist/core/testkit/index.mjs +40 -26
  118. package/dist/index.d.mts +21 -16
  119. package/dist/index.mjs +10 -6
  120. package/dist/runtime/adapter.d.mts +3 -3
  121. package/dist/runtime/deno.d.mts +3 -3
  122. package/dist/runtime/detect.d.mts +2 -2
  123. package/dist/runtime/node.d.mts +3 -3
  124. package/dist/runtime/paths.d.mts +1 -31
  125. package/dist/runtime.d.mts +4 -4
  126. package/dist/strings.d.mts +1 -16
  127. package/dist/testkit.d.mts +2 -2
  128. package/dist/testkit.mjs +1 -1
  129. package/dist/version.d.mts +0 -13
  130. package/dist/version.mjs +2 -2
  131. package/dreamcli.schema.json +368 -78
  132. package/examples/interactive.ts +6 -5
  133. package/package.json +12 -11
  134. package/skills/cli-creation/SKILL.md +72 -16
  135. package/skills/cli-creation/references/pattern-cookbook.md +169 -11
  136. package/dist/core/resolve/property.d.mts +0 -51
  137. package/dist/core/resolve/property.mjs +0 -53
@@ -0,0 +1,206 @@
1
+ import { splitBindingOf } from "./cardinality.mjs";
2
+ import { stdinReadsOnDash, stdinReadsWhenMissing } from "./stdin.mjs";
3
+ //#region src/core/schema/source.ts
4
+ /**
5
+ * Ordered resolution stages, highest precedence first.
6
+ *
7
+ * Both surfaces walk this one list. An explicit `-` is CLI-sourced with bytes
8
+ * from stdin, so it lands on `'cli'`; the `'stdin'` stage is the implicit
9
+ * fallback an absent CLI value takes before env.
10
+ */
11
+ const RESOLUTION_ORDER = [
12
+ "cli",
13
+ "stdin",
14
+ "env",
15
+ "config",
16
+ "prompt",
17
+ "default"
18
+ ];
19
+ const PROMPT_RANK = RESOLUTION_ORDER.indexOf("prompt");
20
+ /** Position of a stage in {@link RESOLUTION_ORDER}. */
21
+ function stageRank(stage) {
22
+ return RESOLUTION_ORDER.indexOf(stage);
23
+ }
24
+ /**
25
+ * Project a flag or arg schema onto its source axis.
26
+ *
27
+ * Every input accepts CLI input, so the list always opens with `'cli'`. The
28
+ * remaining entries appear in {@link RESOLUTION_ORDER} order, and only for the
29
+ * sources the schema actually declares. The resolver walks this list, so a
30
+ * source the list omits is a source no stage can produce.
31
+ *
32
+ * A config value is native when it is an array or an object, and a config
33
+ * string decodes under the environment policy, which is the delimited form a
34
+ * user would have typed. A prompt answer reads the same way.
35
+ *
36
+ * @param schema - The flag or arg schema to read.
37
+ * @returns The declared sources, ordered by precedence.
38
+ */
39
+ function sourceBindings(schema) {
40
+ const splitting = splitBindingOf(schema.separator, schema.split);
41
+ const bindings = [{
42
+ stage: "cli",
43
+ split: splitting.cli
44
+ }];
45
+ const stdin = schema.stdin;
46
+ if (stdin !== void 0) bindings.push({
47
+ stage: "stdin",
48
+ when: stdin.when,
49
+ consume: stdin.consume,
50
+ trim: stdin.trim,
51
+ split: splitting.stdin
52
+ });
53
+ if (schema.envVar !== void 0) bindings.push({
54
+ stage: "env",
55
+ envVar: schema.envVar,
56
+ split: splitting.env
57
+ });
58
+ if (schema.configPath !== void 0) bindings.push({
59
+ stage: "config",
60
+ configPath: schema.configPath,
61
+ split: splitting.env
62
+ });
63
+ if (schema.prompt !== void 0) bindings.push({
64
+ stage: "prompt",
65
+ prompt: schema.prompt,
66
+ split: splitting.env
67
+ });
68
+ if (schema.defaultValue !== void 0) bindings.push({
69
+ stage: "default",
70
+ defaultValue: schema.defaultValue
71
+ });
72
+ return bindings;
73
+ }
74
+ /**
75
+ * The stdin source of an input, or `undefined` when it declares none.
76
+ *
77
+ * @param bindings - One input's source list.
78
+ * @returns The stdin binding, when the list carries one.
79
+ */
80
+ function stdinBindingOf(bindings) {
81
+ for (const binding of bindings) if (binding.stage === "stdin") return binding;
82
+ }
83
+ /**
84
+ * The bindings an interactive resolver has not yet had a say in.
85
+ *
86
+ * @param bindings - One input's source list.
87
+ * @returns The entries ranked before `'prompt'`.
88
+ */
89
+ function bindingsBeforePrompt(bindings) {
90
+ return bindings.filter((binding) => stageRank(binding.stage) < PROMPT_RANK);
91
+ }
92
+ /**
93
+ * The bindings left once an interactive resolver has run.
94
+ *
95
+ * @param bindings - One input's source list.
96
+ * @returns The entries ranked at or after `'prompt'`.
97
+ */
98
+ function bindingsFromPrompt(bindings) {
99
+ return bindings.filter((binding) => stageRank(binding.stage) >= PROMPT_RANK);
100
+ }
101
+ /**
102
+ * Replace the prompt binding with the config this invocation actually uses.
103
+ *
104
+ * `.interactive()` may hand a prompt to an input that declares none, or take
105
+ * away the one it declares, so the effective list is per invocation rather than
106
+ * per schema.
107
+ *
108
+ * @param schema - The flag or arg the list belongs to, read for its splitting.
109
+ * @param bindings - One input's source list.
110
+ * @param prompt - The prompt config to use, or `undefined` for no prompt.
111
+ * @returns The list with its prompt binding set to `prompt`.
112
+ */
113
+ function withPromptBinding(schema, bindings, prompt) {
114
+ const rest = bindings.filter((binding) => binding.stage !== "prompt");
115
+ if (prompt === void 0) return rest;
116
+ const after = rest.findIndex((binding) => stageRank(binding.stage) > PROMPT_RANK);
117
+ const at = after === -1 ? rest.length : after;
118
+ const split = splitBindingOf(schema.separator, schema.split).env;
119
+ return [
120
+ ...rest.slice(0, at),
121
+ {
122
+ stage: "prompt",
123
+ prompt,
124
+ split
125
+ },
126
+ ...rest.slice(at)
127
+ ];
128
+ }
129
+ /**
130
+ * List the stdin consumers declared across a command's flags and args.
131
+ *
132
+ * @param flags - The command's flag schemas keyed by name.
133
+ * @param args - The command's positional entries in declaration order.
134
+ * @returns Every stdin-enabled input, flags first, then args in declaration order.
135
+ */
136
+ function stdinConsumers(flags, args) {
137
+ const consumers = [];
138
+ for (const [name, schema] of Object.entries(flags)) if (schema.stdin !== void 0) consumers.push({
139
+ kind: "flag",
140
+ name,
141
+ stdin: schema.stdin
142
+ });
143
+ for (const { name, schema } of args) if (schema.stdin !== void 0) consumers.push({
144
+ kind: "arg",
145
+ name,
146
+ stdin: schema.stdin
147
+ });
148
+ return consumers;
149
+ }
150
+ /** How a stdin consumer is spelled on the command line: `--out` or `<out>`. */
151
+ function stdinConsumerReference(consumer) {
152
+ return consumer.kind === "flag" ? `--${consumer.name}` : `<${consumer.name}>`;
153
+ }
154
+ /**
155
+ * Whether this invocation will actually select a stdin source.
156
+ *
157
+ * A `'dash'` binding fires when its token is `-`. A `'missing'` binding fires
158
+ * when argv left the input absent; env, config, prompt, and default do not
159
+ * suppress it, because the stdin fallback outranks all four. Callers use this
160
+ * to decide whether reading the stream is warranted at all.
161
+ *
162
+ * @param flags - Declared flags keyed by canonical name.
163
+ * @param args - Declared positionals in CLI order.
164
+ * @param parsed - What the parser read off argv.
165
+ * @returns `true` when at least one input would read stdin.
166
+ */
167
+ function invocationSelectsStdin(flags, args, parsed) {
168
+ for (const [name, schema] of Object.entries(flags)) {
169
+ const present = Object.hasOwn(parsed.flags, name);
170
+ if (inputSelectsStdin(schema.stdin, present, present ? parsed.flags[name] : void 0)) return true;
171
+ }
172
+ for (const { name, schema } of args) {
173
+ const present = Object.hasOwn(parsed.args, name);
174
+ const value = present ? parsed.args[name] : void 0;
175
+ if (inputSelectsStdin(schema.stdin, present && !argCollectedNothing(schema, value), value)) return true;
176
+ }
177
+ return false;
178
+ }
179
+ /**
180
+ * Whether a variadic arg's parsed value means its tail collected nothing.
181
+ *
182
+ * A variadic arg always has a key in the parser's record, and an empty list is
183
+ * how it spells an empty tail, so an input that reads stdin when missing is
184
+ * still missing here.
185
+ *
186
+ * @param schema - The positional's schema.
187
+ * @param value - What the parser produced for it.
188
+ * @returns `true` when the tail took no token.
189
+ */
190
+ function argCollectedNothing(schema, value) {
191
+ return schema.variadic && Array.isArray(value) && value.length === 0;
192
+ }
193
+ /**
194
+ * Whether one input's stdin binding fires for the value argv left it.
195
+ *
196
+ * A collection keeps its occurrences in a list until resolution splices them,
197
+ * so a `-` among them selects stdin exactly as a lone `-` does for a scalar.
198
+ */
199
+ function inputSelectsStdin(stdin, present, value) {
200
+ if (stdin === void 0) return false;
201
+ if (!present || value === void 0) return stdinReadsWhenMissing(stdin);
202
+ if (!stdinReadsOnDash(stdin)) return false;
203
+ return Array.isArray(value) ? value.includes("-") : value === "-";
204
+ }
205
+ //#endregion
206
+ export { RESOLUTION_ORDER, argCollectedNothing, bindingsBeforePrompt, bindingsFromPrompt, invocationSelectsStdin, sourceBindings, stdinBindingOf, stdinConsumerReference, stdinConsumers, withPromptBinding };
@@ -11,12 +11,12 @@
11
11
  /** A schema that conforms to the Standard Schema v1 specification. */
12
12
  interface StandardSchemaV1<Input = unknown, Output = Input> {
13
13
  /** The Standard Schema properties, namespaced under a well-known key. */
14
- readonly '~standard': StandardSchemaV1.Props<Input, Output>;
14
+ readonly "~standard": StandardSchemaV1.Props<Input, Output>;
15
15
  }
16
16
  /** Types copied from the Standard Schema v1 specification. */
17
17
  declare namespace StandardSchemaV1 {
18
18
  /** The properties exposed under a validator's `~standard` key. */
19
- interface Props<Input = unknown, Output = Input> {
19
+ export interface Props<Input = unknown, Output = Input> {
20
20
  /** The version number of the specification. */
21
21
  readonly version: 1;
22
22
  /** The vendor name of the schema library. */
@@ -27,47 +27,47 @@ declare namespace StandardSchemaV1 {
27
27
  readonly types?: Types<Input, Output> | undefined;
28
28
  }
29
29
  /** Optional parameters passed to a validator. */
30
- interface Options {
30
+ export interface Options {
31
31
  /** Explicit support for vendor-specific validation parameters. */
32
32
  readonly libraryOptions?: Record<string, unknown> | undefined;
33
33
  }
34
34
  /** The result of validating a value: either its output or a list of issues. */
35
- type Result<Output> = SuccessResult<Output> | FailureResult;
35
+ export type Result<Output> = SuccessResult<Output> | FailureResult;
36
36
  /** A successful validation carrying the parsed output value. */
37
- interface SuccessResult<Output> {
37
+ export interface SuccessResult<Output> {
38
38
  /** The validated (and possibly transformed) value. */
39
39
  readonly value: Output;
40
40
  /** Absent on success. */
41
41
  readonly issues?: undefined;
42
42
  }
43
43
  /** A failed validation carrying validation issues. */
44
- interface FailureResult {
44
+ export interface FailureResult {
45
45
  /** The issues that caused validation to fail. */
46
46
  readonly issues: ReadonlyArray<Issue>;
47
47
  }
48
48
  /** A single validation issue. */
49
- interface Issue {
49
+ export interface Issue {
50
50
  /** The human-readable error message. */
51
51
  readonly message: string;
52
52
  /** The path to the offending value, when the validator reports one. */
53
53
  readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
54
54
  }
55
55
  /** One segment of an issue path. */
56
- interface PathSegment {
56
+ export interface PathSegment {
57
57
  /** The key of this path segment. */
58
58
  readonly key: PropertyKey;
59
59
  }
60
60
  /** The type-level input and output carried by a validator. */
61
- interface Types<Input = unknown, Output = Input> {
61
+ export interface Types<Input = unknown, Output = Input> {
62
62
  /** The input type accepted by the validator. */
63
63
  readonly input: Input;
64
64
  /** The output type produced by the validator. */
65
65
  readonly output: Output;
66
66
  }
67
67
  /** Infer the input type of a Standard Schema validator. */
68
- type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
68
+ export type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["input"];
69
69
  /** Infer the output type of a Standard Schema validator. */
70
- type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
70
+ export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
71
71
  }
72
72
  /** Backward-compatible flat alias for {@link StandardSchemaV1.Props}. */
73
73
  type StandardSchemaV1Props<Input = unknown, Output = Input> = StandardSchemaV1.Props<Input, Output>;
@@ -89,12 +89,5 @@ type StandardSchemaV1Types<Input = unknown, Output = Input> = StandardSchemaV1.T
89
89
  type InferStandardInput<Schema extends StandardSchemaV1> = StandardSchemaV1.InferInput<Schema>;
90
90
  /** Flat alias for {@link StandardSchemaV1.InferOutput}. */
91
91
  type InferStandardOutput<Schema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<Schema>;
92
- /**
93
- * Detect a Standard Schema validator without assuming validators are plain
94
- * objects. Some conforming libraries expose callable schema values.
95
- *
96
- * @internal
97
- */
98
- declare function isStandardSchemaV1(value: unknown): value is StandardSchemaV1;
99
92
  //#endregion
100
- export { InferStandardInput, InferStandardOutput, StandardSchemaV1, StandardSchemaV1FailureResult, StandardSchemaV1Issue, StandardSchemaV1Options, StandardSchemaV1PathSegment, StandardSchemaV1Props, StandardSchemaV1Result, StandardSchemaV1SuccessResult, StandardSchemaV1Types, isStandardSchemaV1 };
93
+ export { InferStandardInput, InferStandardOutput, StandardSchemaV1, StandardSchemaV1FailureResult, StandardSchemaV1Issue, StandardSchemaV1Options, StandardSchemaV1PathSegment, StandardSchemaV1Props, StandardSchemaV1Result, StandardSchemaV1SuccessResult, StandardSchemaV1Types };
@@ -0,0 +1,87 @@
1
+ //#region src/core/schema/stdin.d.ts
2
+ /** All stdin trigger modes as a runtime array. */
3
+ declare const STDIN_WHENS: readonly ["dash", "missing", "dash-or-missing"];
4
+ /**
5
+ * When a stdin-enabled input reads the stdin stream.
6
+ *
7
+ * - `'dash'` — only an explicit `-` selects stdin; an absent input falls
8
+ * through to the later sources
9
+ * - `'missing'` — only an absent input selects stdin; a `-` stays the literal
10
+ * string `'-'`
11
+ * - `'dash-or-missing'` — both select stdin
12
+ */
13
+ type StdinWhen = (typeof STDIN_WHENS)[number];
14
+ /** All stdin consumption modes as a runtime array. */
15
+ declare const STDIN_CONSUMES: readonly ["exclusive", "broadcast"];
16
+ /**
17
+ * How a stdin-enabled input shares the stream with the command's other inputs.
18
+ *
19
+ * - `'exclusive'` — this input is the command's only stdin consumer, and a
20
+ * second exclusive consumer is a schema error
21
+ * - `'broadcast'` — every broadcast consumer on the command receives the same
22
+ * buffer
23
+ */
24
+ type StdinConsume = (typeof STDIN_CONSUMES)[number];
25
+ /** The normalized stdin axis of a flag or an arg. */
26
+ interface StdinBinding {
27
+ /** When this input reads the stdin stream. */
28
+ readonly when: StdinWhen;
29
+ /** Whether this input consumes the stream alone. */
30
+ readonly consume: StdinConsume;
31
+ /** Whether one trailing line terminator is dropped from a single value. */
32
+ readonly trim: boolean;
33
+ }
34
+ /** Stdin settings accepted by `.stdin()` and by the schema definitions. */
35
+ interface StdinOptions {
36
+ /**
37
+ * When this input reads the stdin stream.
38
+ * @defaultValue `'dash-or-missing'`
39
+ */
40
+ readonly when?: StdinWhen | undefined;
41
+ /**
42
+ * Whether this input consumes the stream alone.
43
+ * @defaultValue `'exclusive'`
44
+ */
45
+ readonly consume?: StdinConsume | undefined;
46
+ /**
47
+ * Drop one trailing `\n`, `\r\n`, or `\r` from a single value read off the
48
+ * stream, so `echo ./dir | mycli` delivers `'./dir'`. A string is the one
49
+ * kind that still carries the terminator at that point; every other kind
50
+ * drops it while decoding and is unaffected.
51
+ * @defaultValue `false`
52
+ */
53
+ readonly trim?: boolean | undefined;
54
+ }
55
+ /** The binding `.stdin()` produces when called without options. */
56
+ declare const DEFAULT_STDIN_BINDING: StdinBinding;
57
+ /**
58
+ * Reject stdin settings that name a mode outside the declared unions.
59
+ *
60
+ * @param options - Stdin settings from a builder call or a schema definition.
61
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on an unknown mode.
62
+ */
63
+ declare function assertStdinOptions(options: StdinOptions): void;
64
+ /**
65
+ * Normalize stdin settings into the binding a schema stores.
66
+ *
67
+ * @param options - Stdin settings, or `undefined` for every default.
68
+ * @returns A fully populated {@link StdinBinding}.
69
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on an unknown mode.
70
+ */
71
+ declare function normalizeStdinBinding(options?: StdinOptions): StdinBinding;
72
+ /**
73
+ * Whether an explicit `-` selects stdin for this binding.
74
+ *
75
+ * @param binding - Anything carrying the stdin trigger.
76
+ * @returns `true` for `'dash'` and `'dash-or-missing'`.
77
+ */
78
+ declare function stdinReadsOnDash(binding: Pick<StdinBinding, "when">): boolean;
79
+ /**
80
+ * Whether an absent CLI value selects stdin for this binding.
81
+ *
82
+ * @param binding - Anything carrying the stdin trigger.
83
+ * @returns `true` for `'missing'` and `'dash-or-missing'`.
84
+ */
85
+ declare function stdinReadsWhenMissing(binding: Pick<StdinBinding, "when">): boolean;
86
+ //#endregion
87
+ export { DEFAULT_STDIN_BINDING, STDIN_CONSUMES, STDIN_WHENS, type StdinBinding, type StdinConsume, type StdinOptions, type StdinWhen, assertStdinOptions, normalizeStdinBinding, stdinReadsOnDash, stdinReadsWhenMissing };
@@ -0,0 +1,91 @@
1
+ import { CLIError } from "../errors/index.mjs";
2
+ //#region src/core/schema/stdin.ts
3
+ /**
4
+ * The stdin binding shared by the `flag` and `arg` factories.
5
+ *
6
+ * A {@link StdinBinding} says when an input reads the stdin stream, whether it
7
+ * consumes the stream alone, and whether a single value drops the terminator a
8
+ * pipe appends. Both factories store one of these under their `stdin` field, and
9
+ * the parse, preflight, and resolve pipelines read the stdin axis through it.
10
+ *
11
+ * @module dreamcli/core/schema/stdin
12
+ */
13
+ /** All stdin trigger modes as a runtime array. */
14
+ const STDIN_WHENS = [
15
+ "dash",
16
+ "missing",
17
+ "dash-or-missing"
18
+ ];
19
+ /** All stdin consumption modes as a runtime array. */
20
+ const STDIN_CONSUMES = ["exclusive", "broadcast"];
21
+ /** The binding `.stdin()` produces when called without options. */
22
+ const DEFAULT_STDIN_BINDING = {
23
+ when: "dash-or-missing",
24
+ consume: "exclusive",
25
+ trim: false
26
+ };
27
+ /**
28
+ * Reject stdin settings that name a mode outside the declared unions.
29
+ *
30
+ * @param options - Stdin settings from a builder call or a schema definition.
31
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on an unknown mode.
32
+ */
33
+ function assertStdinOptions(options) {
34
+ if (options.when !== void 0 && !STDIN_WHENS.includes(options.when)) throw new CLIError(`Unknown stdin mode '${String(options.when)}'`, {
35
+ code: "INVALID_SCHEMA",
36
+ details: {
37
+ when: options.when,
38
+ allowed: [...STDIN_WHENS]
39
+ },
40
+ suggest: `Use one of: ${STDIN_WHENS.join(", ")}`
41
+ });
42
+ if (options.consume !== void 0 && !STDIN_CONSUMES.includes(options.consume)) throw new CLIError(`Unknown stdin consumption mode '${String(options.consume)}'`, {
43
+ code: "INVALID_SCHEMA",
44
+ details: {
45
+ consume: options.consume,
46
+ allowed: [...STDIN_CONSUMES]
47
+ },
48
+ suggest: `Use one of: ${STDIN_CONSUMES.join(", ")}`
49
+ });
50
+ if (options.trim !== void 0 && typeof options.trim !== "boolean") throw new CLIError(`Stdin trim must be a boolean, received '${String(options.trim)}'`, {
51
+ code: "INVALID_SCHEMA",
52
+ details: { trim: options.trim },
53
+ suggest: "Pass trim: true or trim: false"
54
+ });
55
+ }
56
+ /**
57
+ * Normalize stdin settings into the binding a schema stores.
58
+ *
59
+ * @param options - Stdin settings, or `undefined` for every default.
60
+ * @returns A fully populated {@link StdinBinding}.
61
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on an unknown mode.
62
+ */
63
+ function normalizeStdinBinding(options) {
64
+ if (options === void 0) return DEFAULT_STDIN_BINDING;
65
+ assertStdinOptions(options);
66
+ return {
67
+ when: options.when ?? DEFAULT_STDIN_BINDING.when,
68
+ consume: options.consume ?? DEFAULT_STDIN_BINDING.consume,
69
+ trim: options.trim ?? DEFAULT_STDIN_BINDING.trim
70
+ };
71
+ }
72
+ /**
73
+ * Whether an explicit `-` selects stdin for this binding.
74
+ *
75
+ * @param binding - Anything carrying the stdin trigger.
76
+ * @returns `true` for `'dash'` and `'dash-or-missing'`.
77
+ */
78
+ function stdinReadsOnDash(binding) {
79
+ return binding.when === "dash" || binding.when === "dash-or-missing";
80
+ }
81
+ /**
82
+ * Whether an absent CLI value selects stdin for this binding.
83
+ *
84
+ * @param binding - Anything carrying the stdin trigger.
85
+ * @returns `true` for `'missing'` and `'dash-or-missing'`.
86
+ */
87
+ function stdinReadsWhenMissing(binding) {
88
+ return binding.when === "missing" || binding.when === "dash-or-missing";
89
+ }
90
+ //#endregion
91
+ export { DEFAULT_STDIN_BINDING, STDIN_CONSUMES, STDIN_WHENS, assertStdinOptions, normalizeStdinBinding, stdinReadsOnDash, stdinReadsWhenMissing };
@@ -47,15 +47,15 @@ interface StringConstraints {
47
47
  * the source so callers can render them.
48
48
  */
49
49
  type StringConstraintViolation = {
50
- readonly kind: 'nonEmpty';
50
+ readonly kind: "nonEmpty";
51
51
  } | {
52
- readonly kind: 'minLength';
52
+ readonly kind: "minLength";
53
53
  readonly bound: number;
54
54
  } | {
55
- readonly kind: 'maxLength';
55
+ readonly kind: "maxLength";
56
56
  readonly bound: number;
57
57
  } | {
58
- readonly kind: 'pattern';
58
+ readonly kind: "pattern";
59
59
  readonly pattern: string;
60
60
  };
61
61
  /**
@@ -79,6 +79,17 @@ declare function validateStringConstraints(value: string, constraints: StringCon
79
79
  * @returns A message suffix such as `must not be empty` or `must match /^ghp_/`.
80
80
  */
81
81
  declare function describeStringConstraintViolation(violation: StringConstraintViolation): string;
82
+ /**
83
+ * Build the error-detail fields naming the rule a value broke.
84
+ *
85
+ * The parse path for flags and args and the resolver coercion path for env,
86
+ * config, prompt, and stdin all attach these fields, so a consumer reading
87
+ * `details` gets one shape wherever the failure came from.
88
+ *
89
+ * @param violation - The violation to describe.
90
+ * @returns `constraint` plus the bound or pattern the violation carries.
91
+ */
92
+ declare function stringConstraintDetails(violation: StringConstraintViolation): Readonly<Record<string, unknown>>;
82
93
  /**
83
94
  * Assert that a constraints object is well-formed at schema-construction time.
84
95
  *
@@ -94,4 +105,4 @@ declare function describeStringConstraintViolation(violation: StringConstraintVi
94
105
  */
95
106
  declare function assertStringConstraints(constraints: StringConstraints): void;
96
107
  //#endregion
97
- export { type StringConstraintViolation, type StringConstraints, assertStringConstraints, describeStringConstraintViolation, validateStringConstraints };
108
+ export { type StringConstraintViolation, type StringConstraints, assertStringConstraints, describeStringConstraintViolation, stringConstraintDetails, validateStringConstraints };
@@ -46,6 +46,23 @@ function describeStringConstraintViolation(violation) {
46
46
  }
47
47
  }
48
48
  /**
49
+ * Build the error-detail fields naming the rule a value broke.
50
+ *
51
+ * The parse path for flags and args and the resolver coercion path for env,
52
+ * config, prompt, and stdin all attach these fields, so a consumer reading
53
+ * `details` gets one shape wherever the failure came from.
54
+ *
55
+ * @param violation - The violation to describe.
56
+ * @returns `constraint` plus the bound or pattern the violation carries.
57
+ */
58
+ function stringConstraintDetails(violation) {
59
+ return {
60
+ constraint: violation.kind,
61
+ ..."bound" in violation ? { bound: violation.bound } : {},
62
+ ..."pattern" in violation ? { pattern: violation.pattern } : {}
63
+ };
64
+ }
65
+ /**
49
66
  * Assert that a constraints object is well-formed at schema-construction time.
50
67
  *
51
68
  * Length bounds must be non-negative integers — a fractional or negative
@@ -66,4 +83,4 @@ function assertStringConstraints(constraints) {
66
83
  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
84
  }
68
85
  //#endregion
69
- export { assertStringConstraints, describeStringConstraintViolation, validateStringConstraints };
86
+ export { assertStringConstraints, describeStringConstraintViolation, stringConstraintDetails, validateStringConstraints };
@@ -1,17 +1,21 @@
1
1
  //#region src/core/schema/value-parsers.d.ts
2
2
  /**
3
- * Parse functions backing the sugar flag factories (`flag.url()`,
4
- * `flag.date()`, `flag.duration()`, `flag.bytes()`).
3
+ * Value-level machinery behind the sugar factories on both `flag` and `arg`
4
+ * (`url()`, `path()`, `date()`, `duration()`, `bytes()`).
5
5
  *
6
- * Each parser converts a raw CLI/env/config value into a typed value and
6
+ * Each parser converts a raw CLI/env/config/stdin value into a typed value and
7
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.
8
+ * parse and resolve pipelines wrap thrown errors with the subject's context
9
+ * (`Failed to parse flag --x: <reason>`, `Failed to parse argument <x>: …`),
10
+ * so parsers only describe the value problem itself.
11
+ *
12
+ * The option types keep their `Flag` prefix from the release that introduced
13
+ * them on the flag factory alone. They describe the value, not flag syntax,
14
+ * and the arg factory takes the same objects.
11
15
  *
12
16
  * @module dreamcli/core/schema/value-parsers
13
17
  */
14
- /** Options accepted by `flag.url()`. */
18
+ /** Options accepted by `flag.url()` and `arg.url()`. */
15
19
  interface UrlFlagOptions {
16
20
  /**
17
21
  * Allowed URL protocols, without the trailing colon (e.g. `['https']`).
@@ -19,7 +23,7 @@ interface UrlFlagOptions {
19
23
  */
20
24
  readonly protocols?: readonly string[];
21
25
  }
22
- /** Options accepted by `flag.date()`. */
26
+ /** Options accepted by `flag.date()` and `arg.date()`. */
23
27
  interface DateFlagOptions {
24
28
  /**
25
29
  * Inclusive earliest allowed date.
@@ -74,5 +78,73 @@ declare function parseDurationValue(raw: unknown): number;
74
78
  * @throws Error with a human-readable reason on invalid input.
75
79
  */
76
80
  declare function parseBytesValue(raw: unknown): number;
81
+ /** Options accepted by `flag.path()` and `arg.path()` for any-kind or file paths. */
82
+ interface FilePathFlagOptions {
83
+ /**
84
+ * Reject the value if nothing exists at the path.
85
+ * @defaultValue `false` (`true` when `type` is set)
86
+ */
87
+ readonly mustExist?: boolean;
88
+ /**
89
+ * Require the path to be a file or a directory. Implies existence
90
+ * unless `mustExist` is explicitly `false`, in which case a missing
91
+ * path passes and only an existing path is type-checked.
92
+ * @defaultValue `undefined` (any kind)
93
+ */
94
+ readonly type?: "file";
95
+ /** Directory creation is only available with `type: 'directory'`. */
96
+ readonly create?: never;
97
+ }
98
+ /** Options accepted by `flag.path()` and `arg.path()` for directory paths. */
99
+ interface DirectoryPathFlagOptions {
100
+ /**
101
+ * Reject the value if nothing exists at the path.
102
+ * @defaultValue `false` (`true` when `type` is set)
103
+ */
104
+ readonly mustExist?: boolean;
105
+ /**
106
+ * Require the path to be a directory. Implies existence unless
107
+ * `mustExist` is explicitly `false`, in which case a missing path
108
+ * passes and only an existing path is type-checked.
109
+ */
110
+ readonly type: "directory";
111
+ /**
112
+ * Create the directory (recursively) when nothing exists at the path.
113
+ * An existing non-directory path still fails the type check.
114
+ * @defaultValue `false`
115
+ */
116
+ readonly create?: boolean;
117
+ }
118
+ /** Options accepted by `flag.path()` and `arg.path()`. */
119
+ type PathFlagOptions = FilePathFlagOptions | DirectoryPathFlagOptions;
120
+ /**
121
+ * Filesystem expectations attached by `flag.path()` and `arg.path()`.
122
+ *
123
+ * Checked after resolution (not during parse) via the runtime adapter, so
124
+ * `src/core` stays free of platform I/O and every resolved value is validated
125
+ * whichever source produced it, defaults included.
126
+ */
127
+ interface PathChecks {
128
+ /** Reject the value if nothing exists at the path. */
129
+ readonly mustExist: boolean;
130
+ /**
131
+ * Require the existing path to be a file or a directory. Implies
132
+ * existence when set, unless `mustExist` is `false`.
133
+ */
134
+ readonly type: "file" | "directory" | undefined;
135
+ /** Create the directory (recursively) when nothing exists at the path. */
136
+ readonly create: boolean;
137
+ }
138
+ /**
139
+ * Normalize path factory options into the {@link PathChecks} a schema stores.
140
+ *
141
+ * Options that ask for nothing (absent, `{}`, or `mustExist: false` alone)
142
+ * produce `undefined`, so the schema records no checks and the resolver skips
143
+ * the filesystem entirely.
144
+ *
145
+ * @param options - Options passed to `flag.path()` or `arg.path()`.
146
+ * @returns The checks to store, or `undefined` when none were requested.
147
+ */
148
+ declare function buildPathChecks(options?: PathFlagOptions): PathChecks | undefined;
77
149
  //#endregion
78
- export { type DateFlagOptions, type UrlFlagOptions, parseBytesValue, parseDateValue, parseDurationValue, parseUrlValue };
150
+ export { type DateFlagOptions, type PathChecks, type PathFlagOptions, type UrlFlagOptions, buildPathChecks, parseBytesValue, parseDateValue, parseDurationValue, parseUrlValue };