@kjanat/dreamcli 4.0.0-rc.3 → 4.1.0

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 (212) hide show
  1. package/README.md +5 -7
  2. package/dist/{runtime/adapter.d.mts → adapter-YM5QGi3M.d.mts} +4 -4
  3. package/dist/completion-CUMeOnAz.mjs +6 -0
  4. package/dist/completion.d.mts +90 -0
  5. package/dist/completion.mjs +1 -0
  6. package/dist/config-CrlScpYX.mjs +1 -0
  7. package/dist/config.d.mts +2 -0
  8. package/dist/config.mjs +1 -0
  9. package/dist/core-DvXUolc_.mjs +17 -0
  10. package/dist/{core/json-schema/index.d.mts → index-3l8uj16E.d.mts} +43 -34
  11. package/dist/{core/cli/index.d.mts → index-BAj2y70U.d.mts} +116 -57
  12. package/dist/index-BziI2aKc.d.mts +5440 -0
  13. package/dist/index-Cap0MA2V.d.mts +277 -0
  14. package/dist/index-Cp9kt2t-.d.mts +370 -0
  15. package/dist/index-DWsnGZlx.d.mts +831 -0
  16. package/dist/index.d.mts +190 -41
  17. package/dist/index.mjs +1 -26
  18. package/dist/json-schema-DRlrz_IV.mjs +52 -0
  19. package/dist/json-schema.d.mts +2 -0
  20. package/dist/json-schema.mjs +1 -0
  21. package/dist/package-json-BgE9YjjQ.mjs +3 -0
  22. package/dist/prompt.d.mts +48 -0
  23. package/dist/prompt.mjs +1 -0
  24. package/dist/rolldown-runtime-G4Kt5YOX.mjs +1 -0
  25. package/dist/runtime.d.mts +2 -6
  26. package/dist/runtime.mjs +1 -6
  27. package/dist/terminal-C8KTXjv5.mjs +6 -0
  28. package/dist/test-prompter-v__jT2yG.mjs +1 -0
  29. package/dist/testkit.d.mts +54 -6
  30. package/dist/testkit.mjs +1 -5
  31. package/dist/version.mjs +1 -7
  32. package/dreamcli.schema.json +697 -538
  33. package/package.json +29 -7
  34. package/skills/cli-creation/SKILL.md +16 -11
  35. package/CHANGELOG.md +0 -1116
  36. package/dist/core/cli/builtins.d.mts +0 -117
  37. package/dist/core/cli/builtins.mjs +0 -135
  38. package/dist/core/cli/compiled.d.mts +0 -66
  39. package/dist/core/cli/compiled.mjs +0 -76
  40. package/dist/core/cli/dispatch.d.mts +0 -115
  41. package/dist/core/cli/dispatch.mjs +0 -205
  42. package/dist/core/cli/help-links.d.mts +0 -27
  43. package/dist/core/cli/help-links.mjs +0 -41
  44. package/dist/core/cli/index.mjs +0 -1271
  45. package/dist/core/cli/planner.d.mts +0 -174
  46. package/dist/core/cli/planner.mjs +0 -323
  47. package/dist/core/cli/plugin.d.mts +0 -94
  48. package/dist/core/cli/plugin.mjs +0 -41
  49. package/dist/core/cli/propagate.d.mts +0 -39
  50. package/dist/core/cli/propagate.mjs +0 -57
  51. package/dist/core/cli/reserved-flags.d.mts +0 -19
  52. package/dist/core/cli/reserved-flags.mjs +0 -158
  53. package/dist/core/cli/root-help.d.mts +0 -53
  54. package/dist/core/cli/root-help.mjs +0 -221
  55. package/dist/core/cli/root-output-flags.d.mts +0 -74
  56. package/dist/core/cli/root-output-flags.mjs +0 -169
  57. package/dist/core/cli/root-surface.d.mts +0 -64
  58. package/dist/core/cli/root-surface.mjs +0 -28
  59. package/dist/core/cli/runtime-preflight.d.mts +0 -213
  60. package/dist/core/cli/runtime-preflight.mjs +0 -221
  61. package/dist/core/completion/index.d.mts +0 -76
  62. package/dist/core/completion/index.mjs +0 -90
  63. package/dist/core/completion/shells/bash.d.mts +0 -23
  64. package/dist/core/completion/shells/bash.mjs +0 -312
  65. package/dist/core/completion/shells/fish.d.mts +0 -19
  66. package/dist/core/completion/shells/fish.mjs +0 -164
  67. package/dist/core/completion/shells/powershell.d.mts +0 -13
  68. package/dist/core/completion/shells/powershell.mjs +0 -360
  69. package/dist/core/completion/shells/shared.d.mts +0 -164
  70. package/dist/core/completion/shells/shared.mjs +0 -147
  71. package/dist/core/completion/shells/zsh.d.mts +0 -23
  72. package/dist/core/completion/shells/zsh.mjs +0 -256
  73. package/dist/core/config/index.d.mts +0 -191
  74. package/dist/core/config/index.mjs +0 -285
  75. package/dist/core/config/package-json.d.mts +0 -179
  76. package/dist/core/config/package-json.mjs +0 -353
  77. package/dist/core/errors/index.d.mts +0 -125
  78. package/dist/core/errors/index.mjs +0 -87
  79. package/dist/core/execution/index.d.mts +0 -61
  80. package/dist/core/execution/index.mjs +0 -220
  81. package/dist/core/help/ansi.d.mts +0 -84
  82. package/dist/core/help/ansi.mjs +0 -121
  83. package/dist/core/help/index.d.mts +0 -149
  84. package/dist/core/help/index.mjs +0 -418
  85. package/dist/core/help/theme.d.mts +0 -86
  86. package/dist/core/help/theme.mjs +0 -69
  87. package/dist/core/json-schema/index.mjs +0 -1008
  88. package/dist/core/json-schema/meta-descriptions.generated.d.mts +0 -274
  89. package/dist/core/json-schema/meta-descriptions.generated.mjs +0 -136
  90. package/dist/core/output/activity.d.mts +0 -193
  91. package/dist/core/output/activity.mjs +0 -452
  92. package/dist/core/output/bind.d.mts +0 -37
  93. package/dist/core/output/bind.mjs +0 -56
  94. package/dist/core/output/contracts.d.mts +0 -82
  95. package/dist/core/output/contracts.mjs +0 -57
  96. package/dist/core/output/display-value.d.mts +0 -19
  97. package/dist/core/output/display-value.mjs +0 -32
  98. package/dist/core/output/index.d.mts +0 -344
  99. package/dist/core/output/index.mjs +0 -514
  100. package/dist/core/output/renderers.d.mts +0 -45
  101. package/dist/core/output/renderers.mjs +0 -46
  102. package/dist/core/output/writer.d.mts +0 -39
  103. package/dist/core/output/writer.mjs +0 -12
  104. package/dist/core/parse/index.d.mts +0 -178
  105. package/dist/core/parse/index.mjs +0 -850
  106. package/dist/core/parse/occurrences.d.mts +0 -90
  107. package/dist/core/parse/occurrences.mjs +0 -114
  108. package/dist/core/prompt/index.d.mts +0 -213
  109. package/dist/core/prompt/index.mjs +0 -348
  110. package/dist/core/read-flags/index.d.mts +0 -150
  111. package/dist/core/read-flags/index.mjs +0 -217
  112. package/dist/core/resolve/args.d.mts +0 -39
  113. package/dist/core/resolve/args.mjs +0 -182
  114. package/dist/core/resolve/coerce.d.mts +0 -79
  115. package/dist/core/resolve/coerce.mjs +0 -900
  116. package/dist/core/resolve/config.d.mts +0 -10
  117. package/dist/core/resolve/config.mjs +0 -19
  118. package/dist/core/resolve/contracts.d.mts +0 -146
  119. package/dist/core/resolve/errors.d.mts +0 -10
  120. package/dist/core/resolve/errors.mjs +0 -148
  121. package/dist/core/resolve/flags.d.mts +0 -74
  122. package/dist/core/resolve/flags.mjs +0 -246
  123. package/dist/core/resolve/index.d.mts +0 -44
  124. package/dist/core/resolve/index.mjs +0 -123
  125. package/dist/core/resolve/path-checks.d.mts +0 -48
  126. package/dist/core/resolve/path-checks.mjs +0 -102
  127. package/dist/core/resolve/redaction.d.mts +0 -13
  128. package/dist/core/resolve/redaction.mjs +0 -14
  129. package/dist/core/resolve/stages.d.mts +0 -86
  130. package/dist/core/resolve/stages.mjs +0 -170
  131. package/dist/core/resolve/standard.d.mts +0 -26
  132. package/dist/core/resolve/standard.mjs +0 -212
  133. package/dist/core/schema/activity.d.mts +0 -189
  134. package/dist/core/schema/arg.d.mts +0 -1461
  135. package/dist/core/schema/arg.mjs +0 -1139
  136. package/dist/core/schema/brand.d.mts +0 -17
  137. package/dist/core/schema/cardinality.d.mts +0 -302
  138. package/dist/core/schema/cardinality.mjs +0 -514
  139. package/dist/core/schema/command.d.mts +0 -1132
  140. package/dist/core/schema/command.mjs +0 -999
  141. package/dist/core/schema/flag.d.mts +0 -1495
  142. package/dist/core/schema/flag.mjs +0 -1207
  143. package/dist/core/schema/index.d.mts +0 -15
  144. package/dist/core/schema/index.mjs +0 -10
  145. package/dist/core/schema/middleware.d.mts +0 -129
  146. package/dist/core/schema/middleware.mjs +0 -41
  147. package/dist/core/schema/number-constraints.d.mts +0 -96
  148. package/dist/core/schema/number-constraints.mjs +0 -60
  149. package/dist/core/schema/prompt.d.mts +0 -135
  150. package/dist/core/schema/provenance.d.mts +0 -99
  151. package/dist/core/schema/provenance.mjs +0 -28
  152. package/dist/core/schema/run.d.mts +0 -211
  153. package/dist/core/schema/source.d.mts +0 -180
  154. package/dist/core/schema/source.mjs +0 -206
  155. package/dist/core/schema/standard.d.mts +0 -100
  156. package/dist/core/schema/standard.mjs +0 -15
  157. package/dist/core/schema/stdin.d.mts +0 -97
  158. package/dist/core/schema/stdin.mjs +0 -91
  159. package/dist/core/schema/string-constraints.d.mts +0 -108
  160. package/dist/core/schema/string-constraints.mjs +0 -86
  161. package/dist/core/schema/value-parsers.d.mts +0 -150
  162. package/dist/core/schema/value-parsers.mjs +0 -160
  163. package/dist/core/schema/value.d.mts +0 -243
  164. package/dist/core/schema/value.mjs +0 -573
  165. package/dist/core/testkit/index.d.mts +0 -63
  166. package/dist/core/testkit/index.mjs +0 -102
  167. package/dist/runtime/adapter.mjs +0 -92
  168. package/dist/runtime/auto.d.mts +0 -25
  169. package/dist/runtime/auto.mjs +0 -45
  170. package/dist/runtime/deno.d.mts +0 -99
  171. package/dist/runtime/deno.mjs +0 -265
  172. package/dist/runtime/detect.d.mts +0 -86
  173. package/dist/runtime/detect.mjs +0 -45
  174. package/dist/runtime/index.d.mts +0 -6
  175. package/dist/runtime/node.d.mts +0 -71
  176. package/dist/runtime/node.mjs +0 -228
  177. package/dist/runtime/paths.d.mts +0 -31
  178. package/dist/runtime/paths.mjs +0 -48
  179. package/dist/strings.d.mts +0 -27
  180. package/dist/strings.mjs +0 -22
  181. package/examples/basic.ts +0 -37
  182. package/examples/flag-types.ts +0 -79
  183. package/examples/gh/package.json +0 -45
  184. package/examples/gh/src/commands/auth.ts +0 -66
  185. package/examples/gh/src/commands/issue.ts +0 -120
  186. package/examples/gh/src/commands/pr.ts +0 -125
  187. package/examples/gh/src/data/issues.yaml +0 -5
  188. package/examples/gh/src/data/issues.yaml.d.ts +0 -17
  189. package/examples/gh/src/data/pull-requests.yaml +0 -7
  190. package/examples/gh/src/data/pull-requests.yaml.d.ts +0 -18
  191. package/examples/gh/src/docs.ts +0 -11
  192. package/examples/gh/src/lib/auth.ts +0 -37
  193. package/examples/gh/src/lib/utils.ts +0 -17
  194. package/examples/gh/src/main.test.ts +0 -307
  195. package/examples/gh/src/main.ts +0 -46
  196. package/examples/help-config.ts +0 -43
  197. package/examples/interactive.ts +0 -67
  198. package/examples/json-mode.ts +0 -95
  199. package/examples/middleware.ts +0 -71
  200. package/examples/multi-command.ts +0 -66
  201. package/examples/output-extras.ts +0 -46
  202. package/examples/parser-control.ts +0 -40
  203. package/examples/pwsh-demo/README.md +0 -40
  204. package/examples/pwsh-demo/package.json +0 -41
  205. package/examples/pwsh-demo/pwsh-demo.cmd +0 -3
  206. package/examples/pwsh-demo/smoke-powershell.ps1 +0 -218
  207. package/examples/pwsh-demo/src/main.test.ts +0 -45
  208. package/examples/pwsh-demo/src/main.ts +0 -140
  209. package/examples/spinner-progress.ts +0 -49
  210. package/examples/standard-schema.ts +0 -45
  211. package/examples/testing.ts +0 -147
  212. package/examples/transport-launcher.ts +0 -85
@@ -1,217 +0,0 @@
1
- import { CLIError } from "../errors/index.mjs";
2
- import { invocationSelectsStdin } from "../schema/source.mjs";
3
- import { createCommandSchema } from "../schema/command.mjs";
4
- import { buildFlagLookup, flagExpectsValue, parse, requestsHelp, tokenize } from "../parse/index.mjs";
5
- import { formatHelp } from "../help/index.mjs";
6
- import { resolve } from "../resolve/index.mjs";
7
- import { createAdapter } from "../../runtime/auto.mjs";
8
- //#region src/core/read-flags/index.ts
9
- /**
10
- * Standalone typed flag evaluation over the existing builder DSL.
11
- *
12
- * {@linkcode readFlags} runs a record of {@linkcode FlagBuilder} definitions through
13
- * the same command schema, parser, coercion, resolver, and validation that a
14
- * command uses, and returns the values typed by {@linkcode InferFlags}. There is
15
- * no command dispatch here; parse and resolution failures propagate as the
16
- * framework's `ParseError` and `ValidationError`. The one output surface is the
17
- * built-in `--help`: while it is on and no definition claims its spellings, a
18
- * pre-separator `--help` or `-h` prints generated help to the adapter's stdout
19
- * and exits the process with code 0.
20
- *
21
- * @module dreamcli/core/read-flags
22
- */
23
- const INTERNAL_COMMAND_NAME = "<standalone>";
24
- /**
25
- * Reader that yields the injected adapter, or builds one the first time a fact
26
- * the caller did not supply is actually needed.
27
- */
28
- function adapterReader(injected) {
29
- let adapter = injected;
30
- return () => {
31
- adapter ??= createAdapter();
32
- return adapter;
33
- };
34
- }
35
- /**
36
- * The final path segment of the adapter's script entry, for the help usage
37
- * line. Falls back to `script` when the adapter carries no script path.
38
- */
39
- function scriptName(adapter) {
40
- const path = adapter.argv[1] ?? "";
41
- const base = path.slice(Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\")) + 1);
42
- return base === "" ? "script" : base;
43
- }
44
- /**
45
- * Drop argv entries the lookup does not declare: unknown long flags with their
46
- * inline value, unknown characters inside a short group, positional arguments,
47
- * and the `--` separator. The walk mirrors the parser's value consumption, so
48
- * the token after a declared value-expecting flag survives as that flag's
49
- * value while the token after an unknown flag is dropped as a positional.
50
- */
51
- function withoutUndeclaredTokens(argv, lookup) {
52
- const tokens = tokenize(argv);
53
- const kept = [];
54
- let i = 0;
55
- while (i < tokens.length) {
56
- const token = tokens[i];
57
- const raw = argv[i];
58
- if (token === void 0 || raw === void 0) break;
59
- if (token.kind === "positional" || token.kind === "separator") {
60
- i++;
61
- continue;
62
- }
63
- if (token.kind === "long-flag") {
64
- const entry = lookup.get(token.name);
65
- i++;
66
- if (entry === void 0) continue;
67
- kept.push(raw);
68
- if (!entry.negated && token.value === void 0 && flagExpectsValue(entry.schema)) {
69
- const nextRaw = argv[i];
70
- if (tokens[i]?.kind === "positional" && nextRaw !== void 0) {
71
- kept.push(nextRaw);
72
- i++;
73
- }
74
- }
75
- continue;
76
- }
77
- let declared = "";
78
- let awaitsValue = false;
79
- for (let ci = 0; ci < token.chars.length; ci++) {
80
- const ch = token.chars.charAt(ci);
81
- const entry = lookup.get(ch);
82
- if (entry === void 0) continue;
83
- declared += ch;
84
- if (flagExpectsValue(entry.schema)) {
85
- const inline = token.chars.slice(ci + 1);
86
- if (inline.length > 0) declared += inline;
87
- else awaitsValue = true;
88
- break;
89
- }
90
- }
91
- i++;
92
- if (declared.length === 0) continue;
93
- kept.push(`-${declared}`);
94
- if (awaitsValue) {
95
- const nextRaw = argv[i];
96
- if (tokens[i]?.kind === "positional" && nextRaw !== void 0) {
97
- kept.push(nextRaw);
98
- i++;
99
- }
100
- }
101
- }
102
- return kept;
103
- }
104
- /**
105
- * Evaluate a record of flag definitions and return the resolved values.
106
- *
107
- * The record is compiled into an anonymous command schema with no positional
108
- * arguments, parsed once, and run through the CLI, env, config, prompt, default
109
- * resolution chain. Aliases, negated spellings, duplicate policy, case parity,
110
- * unknown-flag rejection, coercion, constraints, Standard Schema validators, and
111
- * `flag.path()` checks behave exactly as they do inside a command.
112
- *
113
- * A pre-separator `--help` or `-h` prints generated help to the adapter's
114
- * stdout and exits with code 0, unless {@linkcode ReadFlagsOptions.help} is
115
- * `'off'` or a definition claims either spelling. With
116
- * {@linkcode ReadFlagsOptions.strict} set to `false`, undeclared argv content
117
- * is dropped instead of rejected, so a script can read its own flags out of an
118
- * argv it shares with another consumer.
119
- *
120
- * Anything the caller leaves out comes from the runtime adapter, which is built
121
- * on first use, so a call given `argv` and `env` reads nothing from the host
122
- * unless a `flag.path()` check needs the adapter's filesystem primitives.
123
- * `config` has no application name to discover a file from and stays
124
- * caller-supplied. `prompter` stays caller-supplied as well, so a `.prompt()`
125
- * flag with no prompter falls through to its default.
126
- *
127
- * @param definitions - Flag builders keyed by canonical flag name.
128
- * @param options - Injected runtime state and behavior toggles.
129
- * @returns The resolved flag values, typed from the definitions.
130
- * @throws {ParseError} For unknown flags, missing values, and bad input.
131
- * @throws {ValidationError} For missing required flags and failed validators.
132
- * @throws {CLIError} With code `'FLAG_NAME_COLLISION'` when two definitions share
133
- * a name, an alias, or a negated spelling.
134
- * @throws {CLIError} With code `'INVALID_SCHEMA'` for the definition key
135
- * `__proto__`, which JavaScript cannot carry as a plain record key, and for a
136
- * definitions record whose prototype is replaced, which hides the entries a
137
- * key check would read.
138
- *
139
- * @example
140
- * ```ts
141
- * import { flag, readFlags } from '@kjanat/dreamcli';
142
- *
143
- * const options = await readFlags({
144
- * watch: flag.boolean().alias('w').env('WATCH').default(false),
145
- * minify: flag.boolean().env('MINIFY').default(true),
146
- * target: flag.enum(['node', 'browser']).env('TARGET').default('node'),
147
- * });
148
- *
149
- * options.watch; // boolean
150
- * options.minify; // boolean
151
- * options.target; // 'node' | 'browser'
152
- * ```
153
- *
154
- * @example
155
- * ```ts
156
- * const values = await readFlags(
157
- * { watch: flag.boolean().alias('w').env('WATCH') },
158
- * { argv: [], env: { WATCH: 'true' } },
159
- * );
160
- *
161
- * values.watch; // true
162
- * ```
163
- *
164
- * @example
165
- * ```ts
166
- * const values = await readFlags(
167
- * { watch: flag.boolean() },
168
- * { argv: ['build', '--watch', '--unknown'], env: {}, strict: false },
169
- * );
170
- *
171
- * values.watch; // true, with 'build' and '--unknown' dropped
172
- * ```
173
- */
174
- async function readFlags(definitions, options) {
175
- for (const key of Reflect.ownKeys(definitions)) if (typeof key !== "string" || !Object.prototype.propertyIsEnumerable.call(definitions, key)) throw new CLIError("Flag definitions must use enumerable string keys", { code: "INVALID_SCHEMA" });
176
- const prototype = Object.getPrototypeOf(definitions);
177
- if (prototype !== Object.prototype && prototype !== null) throw new CLIError("Flag definitions record has a replaced prototype. A '__proto__' key sets the prototype instead of adding a definition, and an inherited definition is never read", {
178
- code: "INVALID_SCHEMA",
179
- suggest: "Pass a plain object with no '__proto__' key, or a record built with Object.create(null)"
180
- });
181
- const entries = Object.entries(definitions);
182
- for (const [name] of entries) if (name === "__proto__") throw new CLIError(`Flag name '${name}' is not usable as a flag`, {
183
- code: "INVALID_SCHEMA",
184
- details: { flag: name },
185
- suggest: "Rename the definition key, for example to \"proto\""
186
- });
187
- const flags = Object.fromEntries(entries.map(([name, builder]) => [name, builder.schema]));
188
- const schema = createCommandSchema({
189
- name: INTERNAL_COMMAND_NAME,
190
- flags
191
- });
192
- const host = adapterReader(options?.adapter);
193
- const argv = options?.argv ?? host().argv.slice(2);
194
- const lookup = buildFlagLookup(schema.flags, options?.parse);
195
- if ((options?.help ?? "on") === "on" && !lookup.has("help") && !lookup.has("h") && requestsHelp(argv)) {
196
- host().stdout(formatHelp(schema, {
197
- binName: scriptName(host()),
198
- isDefaultHelp: true
199
- }));
200
- host().exit(0);
201
- }
202
- const parsed = parse(schema, options?.strict === false ? withoutUndeclaredTokens(argv, lookup) : argv, options?.parse);
203
- const stdinData = options?.stdinData === void 0 && invocationSelectsStdin(schema.flags, schema.args, parsed) ? await host().readStdin() : options?.stdinData;
204
- const resolved = await resolve(schema, parsed, {
205
- env: options?.env ?? host().env,
206
- stat: options?.stat ?? ((path) => host().stat(path)),
207
- mkdir: options?.mkdir ?? ((path) => host().mkdir(path)),
208
- ...options?.config !== void 0 ? { config: options.config } : {},
209
- ...options?.prompter !== void 0 ? { prompter: options.prompter } : {},
210
- ...stdinData !== void 0 ? { stdinData } : {}
211
- });
212
- for (const warning of resolved.deprecations) options?.onDeprecation?.(warning);
213
- options?.onSources?.(resolved.provenance.flags);
214
- return resolved.flags;
215
- }
216
- //#endregion
217
- export { readFlags };
@@ -1,39 +0,0 @@
1
- import { ResolutionProvenance } from "../schema/provenance.mjs";
2
- import { CommandArgEntry } from "../schema/command.mjs";
3
- import { PromptEngine } from "../prompt/index.mjs";
4
- import "../schema/index.mjs";
5
- import { DeprecationWarning } from "./contracts.mjs";
6
- import { MkdirFn, StatFn } from "./path-checks.mjs";
7
- //#region src/core/resolve/args.d.ts
8
- /** External state and collectors one arg-resolution pass shares. */
9
- interface ArgResolutionOptions {
10
- /** Environment variable snapshot. */
11
- readonly env: Readonly<Record<string, string | undefined>>;
12
- /** Parsed config file contents. */
13
- readonly config: Readonly<Record<string, unknown>>;
14
- /** Pre-read stdin content, or `null`/`undefined` when nothing was piped. */
15
- readonly stdinData: string | null | undefined;
16
- /** Interactive prompt engine, absent in non-TTY contexts. */
17
- readonly prompter: PromptEngine | undefined;
18
- /** Collector for notices produced by `.deprecated()` args. */
19
- readonly deprecations: DeprecationWarning[];
20
- /** Filesystem probe for `arg.path()` checks. */
21
- readonly stat: StatFn | undefined;
22
- /** Directory creation for `arg.path()` `create` checks. */
23
- readonly mkdir: MkdirFn | undefined;
24
- /** Receiver for the stage that produced each resolved arg. */
25
- readonly provenance: Record<string, ResolutionProvenance>;
26
- }
27
- /**
28
- * Walk every declared arg through the resolution chain
29
- * (cli -> stdin -> env -> config -> prompt -> default), collecting deprecations
30
- * and throwing aggregated errors.
31
- *
32
- * @param argEntries - Declared positionals in CLI order.
33
- * @param parsedArgs - Values the parser read off argv.
34
- * @param options - External state and collectors for this pass.
35
- * @returns Fully resolved arg values keyed by arg name.
36
- */
37
- declare function resolveArgs(argEntries: readonly CommandArgEntry[], parsedArgs: Readonly<Record<string, unknown>>, options: ArgResolutionOptions): Promise<Readonly<Record<string, unknown>>>;
38
- //#endregion
39
- export { type ArgResolutionOptions, resolveArgs };
@@ -1,182 +0,0 @@
1
- import { ValidationError } from "../errors/index.mjs";
2
- import { argValueSchema, valueEnumValues } from "../schema/value.mjs";
3
- import { argCardinality, dedupe } from "../schema/cardinality.mjs";
4
- import { argCollectedNothing, sourceBindings } from "../schema/source.mjs";
5
- import { resolvePromptConfig } from "../prompt/index.mjs";
6
- import { echoesValue } from "./redaction.mjs";
7
- import { coerceArgValue, finishCliArgValue } from "./coerce.mjs";
8
- import { isNonEmpty, throwAggregatedErrors } from "./errors.mjs";
9
- import { pathValuesOf, validatePathChecks } from "./path-checks.mjs";
10
- import { readCliValue, runStages } from "./stages.mjs";
11
- import { COMPATIBLE_PROMPT_KINDS, promptCompatibilityError } from "./flags.mjs";
12
- //#region src/core/resolve/args.ts
13
- /**
14
- * Internal arg resolution helpers.
15
- *
16
- * @module dreamcli/core/resolve/args
17
- * @internal
18
- */
19
- /**
20
- * Walk every declared arg through the resolution chain
21
- * (cli -> stdin -> env -> config -> prompt -> default), collecting deprecations
22
- * and throwing aggregated errors.
23
- *
24
- * @param argEntries - Declared positionals in CLI order.
25
- * @param parsedArgs - Values the parser read off argv.
26
- * @param options - External state and collectors for this pass.
27
- * @returns Fully resolved arg values keyed by arg name.
28
- */
29
- async function resolveArgs(argEntries, parsedArgs, options) {
30
- const resolved = {};
31
- const errors = [];
32
- const state = {
33
- env: options.env,
34
- config: options.config,
35
- stdinData: options.stdinData,
36
- canPrompt: options.prompter !== void 0
37
- };
38
- for (const { name, schema } of argEntries) {
39
- const bindings = sourceBindings(schema);
40
- const outcome = await runStages(bindings, stageInput(name, schema, parsedArgs, bindings, options.prompter), state);
41
- if (outcome.kind === "error") {
42
- errors.push(outcome.error);
43
- continue;
44
- }
45
- if (outcome.kind === "value") {
46
- if (schema.deprecated !== void 0 && outcome.provenance.stage !== "default") options.deprecations.push({
47
- kind: "arg",
48
- name,
49
- message: schema.deprecated
50
- });
51
- resolved[name] = outcome.value;
52
- options.provenance[name] = outcome.provenance;
53
- continue;
54
- }
55
- const cardinality = argCardinality(schema);
56
- if (cardinality.kind === "many" || cardinality.kind === "entries") {
57
- if (schema.presence === "required") {
58
- errors.push(new ValidationError(`Missing required argument <${name}>`, {
59
- code: "REQUIRED_ARG",
60
- details: {
61
- arg: name,
62
- ...schema.variadic ? { variadic: true } : {}
63
- },
64
- suggest: buildRequiredArgSuggest(name, schema, schema.variadic)
65
- }));
66
- continue;
67
- }
68
- resolved[name] = cardinality.kind === "many" ? [] : {};
69
- options.provenance[name] = { stage: "default" };
70
- continue;
71
- }
72
- if (schema.presence === "required") {
73
- errors.push(new ValidationError(`Missing required argument <${name}>`, {
74
- code: "REQUIRED_ARG",
75
- details: { arg: name },
76
- suggest: buildRequiredArgSuggest(name, schema)
77
- }));
78
- continue;
79
- }
80
- resolved[name] = void 0;
81
- }
82
- for (const { name, schema } of argEntries) {
83
- if (!schema.unique) continue;
84
- const value = Object.hasOwn(resolved, name) ? resolved[name] : void 0;
85
- if (Array.isArray(value)) resolved[name] = [...dedupe(value)];
86
- }
87
- if (options.stat !== void 0) for (const { name, schema } of argEntries) {
88
- const checks = argValueSchema(schema).pathChecks;
89
- if (checks === void 0) continue;
90
- const echo = echoesValue(Object.hasOwn(options.provenance, name) ? options.provenance[name] : void 0);
91
- for (const value of pathValuesOf(Object.hasOwn(resolved, name) ? resolved[name] : void 0)) {
92
- const violation = await validatePathChecks({
93
- kind: "arg",
94
- name
95
- }, value, checks, options.stat, options.mkdir, echo);
96
- if (violation !== void 0) errors.push(violation);
97
- }
98
- }
99
- if (isNonEmpty(errors)) throwAggregatedErrors(errors);
100
- return resolved;
101
- }
102
- /** Assemble what one arg contributes to its own resolution. */
103
- function stageInput(name, schema, parsedArgs, bindings, prompter) {
104
- const present = Object.hasOwn(parsedArgs, name);
105
- const parsedValue = present ? parsedArgs[name] : void 0;
106
- return {
107
- cli: argCollectedNothing(schema, parsedValue) ? { kind: "absent" } : readCliValue(present, parsedValue, bindings),
108
- coerce: (binding, raw) => coerceArgValue(name, binding, raw, schema),
109
- finishCli: (value, stdinData, stdin) => finishCliArgValue(name, schema, value, stdinData, stdin),
110
- runPrompt: async (binding) => prompter === void 0 ? {
111
- ok: false,
112
- error: void 0
113
- } : resolveArgPromptValue(name, schema, binding, prompter)
114
- };
115
- }
116
- /**
117
- * The prompt kinds an arg accepts, read off its value and cardinality axes.
118
- *
119
- * An arg that collects several values takes the prompt a `flag.array()` takes,
120
- * since the two aggregate the same way; every other arg takes what its kind
121
- * takes on the flag surface.
122
- *
123
- * @param schema - The arg schema to read.
124
- * @returns The compatible prompt kinds, and the word a diagnostic names the arg by.
125
- */
126
- function argPromptCompatibility(schema) {
127
- if (argCardinality(schema).kind === "many") return {
128
- allowed: COMPATIBLE_PROMPT_KINDS.array,
129
- kindWord: `variadic ${schema.kind}`
130
- };
131
- return {
132
- allowed: COMPATIBLE_PROMPT_KINDS[schema.kind],
133
- kindWord: schema.kind
134
- };
135
- }
136
- /**
137
- * Validate prompt/arg compatibility, run the prompt engine, and coerce the result.
138
- *
139
- * The compatibility table is the one flags use, read through the value and
140
- * cardinality axes, so the two surfaces accept the same prompt kinds for the
141
- * same value.
142
- * @internal
143
- */
144
- async function resolveArgPromptValue(argName, schema, binding, prompter) {
145
- const promptConfig = binding.prompt;
146
- const { allowed, kindWord } = argPromptCompatibility(schema);
147
- if (!allowed.includes(promptConfig.kind)) return {
148
- ok: false,
149
- error: promptCompatibilityError({
150
- reference: `<${argName}>`,
151
- singular: "argument",
152
- plural: "arguments",
153
- details: {
154
- arg: argName,
155
- argKind: schema.kind
156
- }
157
- }, kindWord, promptConfig.kind, allowed)
158
- };
159
- const resolvedConfig = resolvePromptConfig(promptConfig, valueEnumValues(argValueSchema(schema)));
160
- const result = await prompter.promptOne(resolvedConfig);
161
- if (!result.answered) return {
162
- ok: false,
163
- error: void 0
164
- };
165
- if (promptConfig.kind === "input" && promptConfig.default === void 0 && typeof result.value === "string" && result.value.trim() === "") return {
166
- ok: false,
167
- error: void 0
168
- };
169
- return coerceArgValue(argName, binding, result.value, schema);
170
- }
171
- function buildRequiredArgSuggest(name, schema, variadic) {
172
- const sources = [variadic ? `Provide at least one value for <${name}>` : `Provide a value for <${name}>`];
173
- const stdin = schema.stdin;
174
- if (stdin !== void 0) sources.push(stdin.when === "dash" ? `pass '-' to read stdin` : stdin.when === "missing" ? `pipe a value to stdin` : `pipe a value to stdin or pass '-'`);
175
- if (schema.envVar !== void 0) sources.push(`set ${schema.envVar}`);
176
- if (schema.configPath !== void 0) sources.push(`add ${schema.configPath} to config`);
177
- if (sources.length === 1) return sources[0];
178
- if (sources.length === 2) return `${sources[0]} or ${sources[1]}`;
179
- return `${sources.slice(0, -1).join(", ")}, or ${sources[sources.length - 1]}`;
180
- }
181
- //#endregion
182
- export { resolveArgs };
@@ -1,79 +0,0 @@
1
- import { ValidationError } from "../errors/index.mjs";
2
- import { FlagSchema } from "../schema/flag.mjs";
3
- import { ArgSchema } from "../schema/arg.mjs";
4
- import "../schema/index.mjs";
5
- import { DecodedSourceBinding, StdinSourceBinding } from "../schema/source.mjs";
6
- //#region src/core/resolve/coerce.d.ts
7
- /** Discriminated result of a value coercion attempt — success with the coerced value, or failure with a structured validation error. */
8
- type CoerceResult = {
9
- readonly ok: true;
10
- readonly value: unknown;
11
- } | {
12
- readonly ok: false;
13
- readonly error: ValidationError;
14
- };
15
- /**
16
- * Coerce a raw value from stdin/env/config/prompt into what a flag declares.
17
- *
18
- * The cardinality axis decides how many values the source carries and how they
19
- * combine; the value axis decides what each one means; the binding decides how
20
- * the source's text splits and whether a single value is trimmed.
21
- */
22
- declare function coerceValue(flagName: string, binding: DecodedSourceBinding, raw: unknown, schema: FlagSchema): CoerceResult;
23
- /**
24
- * Coerce a value from a non-CLI source into the type declared by an arg schema,
25
- * redacting the raw value in error diagnostics.
26
- *
27
- * Every source outside argv may carry a secret a user piped, exported, or
28
- * stored, so the arg surface reports the failure without echoing the value.
29
- *
30
- * @param argName - Name of the positional the value belongs to.
31
- * @param binding - The stage that produced the value.
32
- * @param raw - The value that stage produced.
33
- * @param schema - Runtime descriptor of the arg.
34
- * @returns The coerced value, or a redacted {@link ValidationError}.
35
- */
36
- declare function coerceArgValue(argName: string, binding: DecodedSourceBinding, raw: unknown, schema: ArgSchema): CoerceResult;
37
- /** What finishing a CLI-sourced value produced. */
38
- type CliFinish = {
39
- readonly kind: 'value';
40
- readonly value: unknown;
41
- readonly viaStdin: boolean;
42
- } | {
43
- readonly kind: 'error';
44
- readonly error: ValidationError;
45
- } | {
46
- readonly kind: 'absent';
47
- };
48
- /**
49
- * Finish the CLI value of a flag, splicing stdin into occurrence order.
50
- *
51
- * A scalar keeps what the parser produced. A collection carries its occurrences
52
- * in the order they were typed, and an occurrence of `-` stands for the whole
53
- * stdin source at that position: what the buffer decodes to is spliced in
54
- * there, so `--tag before --tag - --tag after` over `'a\nb\n'` resolves to
55
- * `['before', 'a', 'b', 'after']`.
56
- *
57
- * @param flagName - Canonical flag name.
58
- * @param schema - The flag being resolved.
59
- * @param value - What the parser produced for it.
60
- * @param stdinData - The pre-read stdin buffer, when one was read.
61
- * @param stdin - The flag's stdin source, when it declares one.
62
- * @returns The finished value, a failure, or absence when only `-` was given
63
- * and nothing was piped.
64
- */
65
- declare function finishCliFlagValue(flagName: string, schema: FlagSchema, value: unknown, stdinData: string | null | undefined, stdin: StdinSourceBinding | undefined): CliFinish;
66
- /**
67
- * Finish the CLI value of a positional, splicing stdin into occurrence order.
68
- *
69
- * @param argName - Positional arg name.
70
- * @param schema - The arg being resolved.
71
- * @param value - What the parser produced for it.
72
- * @param stdinData - The pre-read stdin buffer, when one was read.
73
- * @param stdin - The arg's stdin source, when it declares one.
74
- * @returns The finished value, a failure, or absence when only `-` was given
75
- * and nothing was piped.
76
- */
77
- declare function finishCliArgValue(argName: string, schema: ArgSchema, value: unknown, stdinData: string | null | undefined, stdin: StdinSourceBinding | undefined): CliFinish;
78
- //#endregion
79
- export { type CliFinish, type CoerceResult, coerceArgValue, coerceValue, finishCliArgValue, finishCliFlagValue };