@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,10 +0,0 @@
1
- //#region src/core/resolve/config.d.ts
2
- /**
3
- * Internal resolver config helpers.
4
- *
5
- * @module dreamcli/core/resolve/config
6
- * @internal
7
- */
8
- declare function resolveConfigPath(config: Readonly<Record<string, unknown>>, path: string): unknown;
9
- //#endregion
10
- export { resolveConfigPath };
@@ -1,19 +0,0 @@
1
- //#region src/core/resolve/config.ts
2
- /**
3
- * Internal resolver config helpers.
4
- *
5
- * @module dreamcli/core/resolve/config
6
- * @internal
7
- */
8
- function resolveConfigPath(config, path) {
9
- const segments = path.split(".");
10
- let current = config;
11
- for (const segment of segments) {
12
- if (current === null || current === void 0 || typeof current !== "object") return;
13
- if (!Object.hasOwn(current, segment)) return;
14
- current = current[segment];
15
- }
16
- return current;
17
- }
18
- //#endregion
19
- export { resolveConfigPath };
@@ -1,146 +0,0 @@
1
- import { ResolutionProvenance } from "../schema/provenance.mjs";
2
- import { CommandSchema } from "../schema/command.mjs";
3
- import { PromptEngine } from "../prompt/index.mjs";
4
- import "../schema/index.mjs";
5
- import { ParseResult } from "../parse/index.mjs";
6
- import { RESOLUTION_ORDER, ResolutionStage } from "../schema/source.mjs";
7
- //#region src/core/resolve/contracts.d.ts
8
- /**
9
- * Source-aware diagnostic context for a resolution failure.
10
- *
11
- * `'cli'` covers the tokens the user typed, which a message names by the input
12
- * alone; the other stages each carry what a message needs to point at the value
13
- * they produced. Both surfaces read the same set.
14
- */
15
- type ResolutionDiagnosticSource = {
16
- readonly kind: 'cli';
17
- } | {
18
- readonly kind: 'stdin';
19
- } | {
20
- readonly kind: 'env';
21
- readonly envVar: string;
22
- } | {
23
- readonly kind: 'config';
24
- readonly configPath: string;
25
- } | {
26
- readonly kind: 'prompt';
27
- };
28
- /**
29
- * The sources whose raw values a resolution stage decodes.
30
- *
31
- * A CLI token is decoded at the parse boundary, so it never reaches the
32
- * coercion diagnostics these name.
33
- */
34
- type DecodedDiagnosticSource = Exclude<ResolutionDiagnosticSource, {
35
- readonly kind: 'cli';
36
- }>;
37
- /** Source-aware diagnostic context for flag resolution failures. */
38
- type FlagDiagnosticSource = DecodedDiagnosticSource;
39
- /** Source-aware diagnostic context for arg resolution failures. */
40
- type ArgDiagnosticSource = DecodedDiagnosticSource;
41
- /**
42
- * External state the resolver may consult after parsing.
43
- *
44
- * The resolver never reaches into `process`, files, or terminal APIs directly;
45
- * callers inject those facts through this contract.
46
- */
47
- interface ResolveOptions {
48
- /** Pre-read stdin content, or `null` when stdin was not piped. */
49
- readonly stdinData?: string | null;
50
- /** Environment variable snapshot injected by the caller. */
51
- readonly env?: Readonly<Record<string, string | undefined>>;
52
- /** Parsed config file contents keyed by dotted path segments. */
53
- readonly config?: Readonly<Record<string, unknown>>;
54
- /** Interactive prompt engine; absent in non-TTY / CI contexts. */
55
- readonly prompter?: PromptEngine;
56
- /**
57
- * Filesystem probe for `flag.path()` and `arg.path()` checks: what exists
58
- * at the path, or `null` when nothing does. When absent, path checks are
59
- * skipped.
60
- */
61
- readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
62
- /**
63
- * Recursive directory creation for `flag.path()` and `arg.path()` `create`
64
- * checks. When absent, missing paths are not created and existence rules
65
- * apply as-is.
66
- */
67
- readonly mkdir?: (path: string) => Promise<void>;
68
- }
69
- /** Structured deprecation notice emitted for explicitly sourced values. */
70
- interface DeprecationWarning {
71
- /** Whether this deprecation targets a flag or a positional arg. */
72
- readonly kind: 'flag' | 'arg';
73
- /** Name of the deprecated flag or arg. */
74
- readonly name: string;
75
- /** Custom deprecation message, or `true` for the generic warning. */
76
- readonly message: string | true;
77
- }
78
- /**
79
- * Which stage produced each resolved value of one command.
80
- *
81
- * The erased form of {@link InputSources}: same records, keyed by plain strings
82
- * because `resolve()` takes a `CommandSchema` rather than typed builders.
83
- */
84
- interface ResolutionProvenanceRecord {
85
- /** Provenance of every declared flag, keyed by flag name. */
86
- readonly flags: Readonly<Record<string, ResolutionProvenance>>;
87
- /** Provenance of every declared arg, keyed by arg name. */
88
- readonly args: Readonly<Record<string, ResolutionProvenance>>;
89
- }
90
- /** Fully resolved command input handed to the executor layer. */
91
- interface ResolveResult {
92
- /** Fully resolved flag values keyed by flag name. */
93
- readonly flags: Readonly<Record<string, unknown>>;
94
- /** Fully resolved positional arg values keyed by arg name. */
95
- readonly args: Readonly<Record<string, unknown>>;
96
- /** Deprecation notices collected during resolution (may be empty). */
97
- readonly deprecations: readonly DeprecationWarning[];
98
- /**
99
- * Which stage produced each value. Present only for inputs that resolved a
100
- * value, so an unset optional input has no entry.
101
- */
102
- readonly provenance: ResolutionProvenanceRecord;
103
- }
104
- /** Explicit invocation boundary between parser output and resolved values. */
105
- interface ResolverInvocation {
106
- /** Command schema that declares flags, args, and resolution metadata. */
107
- readonly schema: CommandSchema;
108
- /** Raw parse result from the tokenizer/parser layer. */
109
- readonly parsed: ParseResult;
110
- /** Optional external state (env, config, stdin, prompter). */
111
- readonly options?: ResolveOptions;
112
- }
113
- /**
114
- * Stable resolver facts the re-foundation workstream is treating as contract.
115
- *
116
- * These are intended to anchor focused contract tests before larger module
117
- * extraction and diagnostic redesign work lands.
118
- */
119
- interface ResolverContract {
120
- /** Ordered stages both surfaces walk: cli -> stdin -> env -> config -> prompt -> default. */
121
- readonly precedence: readonly ResolutionStage[];
122
- /** Flags and args resolve through the same ordered stages. */
123
- readonly flagPrecedence: readonly ResolutionStage[];
124
- /** Flags and args resolve through the same ordered stages. */
125
- readonly argPrecedence: readonly ResolutionStage[];
126
- /** Prompt stage runs only after env and config have been attempted. */
127
- readonly promptRunsAfterFlagConfig: true;
128
- /** The implicit stdin fallback runs before env, so stdin outranks the environment. */
129
- readonly stdinFallbackRunsBeforeEnv: true;
130
- /** An explicit `-` is CLI-sourced with bytes from stdin and keeps CLI precedence. */
131
- readonly dashIsCliSourced: true;
132
- /** All validation errors are collected before throwing a single aggregate. */
133
- readonly aggregatesValidationErrors: true;
134
- /** Aggregate error details include per-issue structured summaries. */
135
- readonly aggregateDiagnosticsIncludePerIssueSummary: true;
136
- /** A coercion failure at any sourced stage stops fallback to later stages for that input. */
137
- readonly hardCoercionErrorsStopFallback: true;
138
- /** Deprecation warnings are emitted only when a value was actually sourced. */
139
- readonly collectsDeprecationsFromExplicitSources: true;
140
- /** Every resolved value records the stage that produced it. */
141
- readonly recordsProvenancePerInput: true;
142
- }
143
- /** Runtime-accessible resolution contract — documents the resolver's invariants for tests and diagnostics. */
144
- declare const resolverContract: ResolverContract;
145
- //#endregion
146
- export { type ArgDiagnosticSource, type DecodedDiagnosticSource, type DeprecationWarning, type FlagDiagnosticSource, RESOLUTION_ORDER, type ResolutionDiagnosticSource, type ResolutionProvenance, type ResolutionProvenanceRecord, type ResolveOptions, type ResolveResult, type ResolverContract, type ResolverInvocation, resolverContract };
@@ -1,10 +0,0 @@
1
- import { ValidationError } from "../errors/index.mjs";
2
- //#region src/core/resolve/errors.d.ts
3
- /** Type-narrowing guard that asserts a readonly array has at least one element. */
4
- declare function isNonEmpty<T>(arr: readonly T[]): arr is readonly [T, ...T[]];
5
- /** Flatten an aggregate validation error's nested `details.errors` into individual errors, or return the original as a singleton. */
6
- declare function collectValidationErrors(error: ValidationError): readonly ValidationError[];
7
- /** Throw a single error if one, or an aggregate with per-issue summaries if many. */
8
- declare function throwAggregatedErrors(errors: readonly [ValidationError, ...ValidationError[]]): never;
9
- //#endregion
10
- export { collectValidationErrors, isNonEmpty, throwAggregatedErrors };
@@ -1,148 +0,0 @@
1
- import { ValidationError } from "../errors/index.mjs";
2
- //#region src/core/resolve/errors.ts
3
- function isRecord(value) {
4
- return typeof value === "object" && value !== null && !Array.isArray(value);
5
- }
6
- function readStringProperty(record, key) {
7
- const value = Reflect.get(record, key);
8
- return typeof value === "string" ? value : void 0;
9
- }
10
- /**
11
- * Name the stage a failure came from, for the aggregate's per-issue label.
12
- *
13
- * Only a failure to read a value carries `source`. A missing required input
14
- * names the env var it would have accepted without claiming the environment
15
- * produced anything.
16
- */
17
- function describeIssueSource(details) {
18
- switch (readStringProperty(details, "source")) {
19
- case "stdin": return {
20
- kind: "stdin",
21
- label: "stdin"
22
- };
23
- case "prompt": return {
24
- kind: "prompt",
25
- label: "prompt"
26
- };
27
- case "env": {
28
- const envVar = readStringProperty(details, "envVar");
29
- return envVar === void 0 ? void 0 : {
30
- kind: "env",
31
- label: `env ${envVar}`
32
- };
33
- }
34
- case "config": {
35
- const configPath = readStringProperty(details, "configPath");
36
- return configPath === void 0 ? void 0 : {
37
- kind: "config",
38
- label: `config ${configPath}`
39
- };
40
- }
41
- default: return;
42
- }
43
- }
44
- function summarizeValidationError(error) {
45
- const details = error.details;
46
- if (!isRecord(details)) return {
47
- code: error.code,
48
- inputKind: "input",
49
- label: "input",
50
- message: error.message
51
- };
52
- const flag = readStringProperty(details, "flag");
53
- if (flag !== void 0) {
54
- const source = describeIssueSource(details);
55
- return {
56
- code: error.code,
57
- inputKind: "flag",
58
- name: flag,
59
- label: `flag --${flag}`,
60
- message: error.message,
61
- ...source !== void 0 ? {
62
- sourceKind: source.kind,
63
- sourceLabel: source.label
64
- } : {}
65
- };
66
- }
67
- const arg = readStringProperty(details, "arg");
68
- if (arg !== void 0) {
69
- const source = describeIssueSource(details);
70
- return {
71
- code: error.code,
72
- inputKind: "arg",
73
- name: arg,
74
- label: `argument <${arg}>`,
75
- message: error.message,
76
- ...source !== void 0 ? {
77
- sourceKind: source.kind,
78
- sourceLabel: source.label
79
- } : {}
80
- };
81
- }
82
- return {
83
- code: error.code,
84
- inputKind: "input",
85
- label: "input",
86
- message: error.message
87
- };
88
- }
89
- function formatAggregateHeadline(issues) {
90
- const flagCount = issues.filter((issue) => issue.inputKind === "flag").length;
91
- const argCount = issues.filter((issue) => issue.inputKind === "arg").length;
92
- const otherCount = issues.length - flagCount - argCount;
93
- const counts = [];
94
- if (flagCount > 0) counts.push(`${flagCount} flag${flagCount === 1 ? "" : "s"}`);
95
- if (argCount > 0) counts.push(`${argCount} arg${argCount === 1 ? "" : "s"}`);
96
- if (otherCount > 0) counts.push(`${otherCount} input${otherCount === 1 ? "" : "s"}`);
97
- return counts.length === 0 ? `Multiple validation errors (${issues.length})` : `Multiple validation errors (${counts.join(", ")})`;
98
- }
99
- function formatAggregateLine(issue) {
100
- const source = issue.sourceLabel !== void 0 ? ` [${issue.sourceLabel}]` : "";
101
- return `${issue.label}${source}: ${issue.message}`;
102
- }
103
- /** Type-narrowing guard that asserts a readonly array has at least one element. */
104
- function isNonEmpty(arr) {
105
- return arr.length > 0;
106
- }
107
- function isValidationErrorJson(value) {
108
- if (value === null || typeof value !== "object") return false;
109
- if (!("code" in value) || !("message" in value) || !("exitCode" in value)) return false;
110
- if (typeof value.code !== "string" || typeof value.message !== "string") return false;
111
- if (typeof value.exitCode !== "number") return false;
112
- if ("suggest" in value && value.suggest !== void 0 && typeof value.suggest !== "string") return false;
113
- if ("details" in value && value.details !== void 0 && (value.details === null || typeof value.details !== "object")) return false;
114
- return true;
115
- }
116
- /** Flatten an aggregate validation error's nested `details.errors` into individual errors, or return the original as a singleton. */
117
- function collectValidationErrors(error) {
118
- const nestedErrors = error.details?.errors;
119
- if (!Array.isArray(nestedErrors)) return [error];
120
- const flattened = [];
121
- for (const entry of nestedErrors) {
122
- if (!isValidationErrorJson(entry)) return [error];
123
- flattened.push(new ValidationError(entry.message, {
124
- code: entry.code,
125
- exitCode: entry.exitCode,
126
- ...entry.suggest !== void 0 ? { suggest: entry.suggest } : {},
127
- ...entry.details !== void 0 ? { details: entry.details } : {}
128
- }));
129
- }
130
- return flattened;
131
- }
132
- /** Throw a single error if one, or an aggregate with per-issue summaries if many. */
133
- function throwAggregatedErrors(errors) {
134
- if (errors.length === 1) throw errors[0];
135
- const issues = errors.map(summarizeValidationError);
136
- const lines = issues.map(formatAggregateLine);
137
- throw new ValidationError(`${formatAggregateHeadline(issues)}:\n - ${lines.join("\n - ")}`, {
138
- code: errors[0].code,
139
- details: {
140
- errors: errors.map((error) => error.toJSON()),
141
- count: errors.length,
142
- issues
143
- },
144
- suggest: "Fix the listed validation errors and retry"
145
- });
146
- }
147
- //#endregion
148
- export { collectValidationErrors, isNonEmpty, throwAggregatedErrors };
@@ -1,74 +0,0 @@
1
- import { ValidationError } from "../errors/index.mjs";
2
- import { PromptKind } from "../schema/prompt.mjs";
3
- import { FlagKind, FlagSchema } from "../schema/flag.mjs";
4
- import { ResolutionProvenance } from "../schema/provenance.mjs";
5
- import { ErasedInteractiveResolver } from "../schema/command.mjs";
6
- import { PromptEngine } from "../prompt/index.mjs";
7
- import { DeprecationWarning } from "./contracts.mjs";
8
- import { MkdirFn, StatFn } from "./path-checks.mjs";
9
- //#region src/core/resolve/flags.d.ts
10
- /** External state and collectors one flag-resolution pass shares. */
11
- interface FlagResolutionOptions {
12
- /** Environment variable snapshot. */
13
- readonly env: Readonly<Record<string, string | undefined>>;
14
- /** Parsed config file contents. */
15
- readonly config: Readonly<Record<string, unknown>>;
16
- /** Pre-read stdin content, or `null`/`undefined` when nothing was piped. */
17
- readonly stdinData: string | null | undefined;
18
- /** Interactive prompt engine, absent in non-TTY contexts. */
19
- readonly prompter: PromptEngine | undefined;
20
- /** Per-invocation prompt overrides declared by `.interactive()`. */
21
- readonly interactive: ErasedInteractiveResolver | undefined;
22
- /** Collector for notices produced by `.deprecated()` flags. */
23
- readonly deprecations: DeprecationWarning[];
24
- /** Filesystem probe for `flag.path()` checks. */
25
- readonly stat: StatFn | undefined;
26
- /** Directory creation for `flag.path()` `create` checks. */
27
- readonly mkdir: MkdirFn | undefined;
28
- /** Receiver for the stage that produced each resolved flag. */
29
- readonly provenance: Record<string, ResolutionProvenance>;
30
- }
31
- /**
32
- * Walk every declared flag through the resolution chain
33
- * (cli -> stdin -> env -> config -> prompt -> default), collecting deprecations
34
- * and throwing aggregated errors.
35
- *
36
- * The chain runs in two passes so `.interactive()` sees what the non-interactive
37
- * sources produced before it decides which flags to prompt for.
38
- *
39
- * @param flagSchemas - Declared flags keyed by canonical name.
40
- * @param parsedFlags - Values the parser read off argv.
41
- * @param options - External state and collectors for this pass.
42
- * @returns Fully resolved flag values keyed by flag name.
43
- */
44
- declare function resolveFlags(flagSchemas: Readonly<Record<string, FlagSchema>>, parsedFlags: Readonly<Record<string, unknown>>, options: FlagResolutionOptions): Promise<Readonly<Record<string, unknown>>>;
45
- /** Maps each flag kind to the prompt kinds that produce compatible values. */
46
- declare const COMPATIBLE_PROMPT_KINDS: Record<FlagKind, readonly PromptKind[]>;
47
- /** How one surface spells the input a prompt-compatibility failure names. */
48
- interface PromptSubject {
49
- /** How the input is written on the command line: `--out` or `<out>`. */
50
- readonly reference: string;
51
- /** What a diagnostic calls one of them: `flag` or `argument`. */
52
- readonly singular: string;
53
- /** What a diagnostic calls several: `flags` or `arguments`. */
54
- readonly plural: string;
55
- /** Identification fields the surface contributes to `details`. */
56
- readonly details: Readonly<Record<string, unknown>>;
57
- }
58
- /**
59
- * Word an incompatible prompt config for the surface that declared it.
60
- *
61
- * A kind with no compatible prompt at all is a different diagnostic from one
62
- * whose prompt is merely the wrong sort, so the empty list gets its own message
63
- * on both surfaces.
64
- *
65
- * @param subject - How the surface spells the input.
66
- * @param kind - The input's declared kind.
67
- * @param promptKind - The prompt kind the config asked for.
68
- * @param allowed - The prompt kinds that kind accepts.
69
- * @returns The error to report.
70
- * @internal
71
- */
72
- declare function promptCompatibilityError(subject: PromptSubject, kind: string, promptKind: PromptKind, allowed: readonly PromptKind[]): ValidationError;
73
- //#endregion
74
- export { COMPATIBLE_PROMPT_KINDS, type FlagResolutionOptions, promptCompatibilityError, resolveFlags };
@@ -1,246 +0,0 @@
1
- import { ValidationError } from "../errors/index.mjs";
2
- import { flagValueSchema, valueEnumValues } from "../schema/value.mjs";
3
- import { dedupe } from "../schema/cardinality.mjs";
4
- import { bindingsBeforePrompt, bindingsFromPrompt, sourceBindings, withPromptBinding } from "../schema/source.mjs";
5
- import { resolvePromptConfig } from "../prompt/index.mjs";
6
- import { echoesValue } from "./redaction.mjs";
7
- import { coerceValue, finishCliFlagValue } 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
- //#region src/core/resolve/flags.ts
12
- /**
13
- * Internal flag resolution helpers.
14
- *
15
- * @module dreamcli/core/resolve/flags
16
- * @internal
17
- */
18
- /**
19
- * Walk every declared flag through the resolution chain
20
- * (cli -> stdin -> env -> config -> prompt -> default), collecting deprecations
21
- * and throwing aggregated errors.
22
- *
23
- * The chain runs in two passes so `.interactive()` sees what the non-interactive
24
- * sources produced before it decides which flags to prompt for.
25
- *
26
- * @param flagSchemas - Declared flags keyed by canonical name.
27
- * @param parsedFlags - Values the parser read off argv.
28
- * @param options - External state and collectors for this pass.
29
- * @returns Fully resolved flag values keyed by flag name.
30
- */
31
- async function resolveFlags(flagSchemas, parsedFlags, options) {
32
- const resolved = {};
33
- const errors = [];
34
- const hardErrorFlags = /* @__PURE__ */ new Set();
35
- const state = {
36
- env: options.env,
37
- config: options.config,
38
- stdinData: options.stdinData,
39
- canPrompt: options.prompter !== void 0
40
- };
41
- for (const [name, schema] of Object.entries(flagSchemas)) {
42
- const bindings = sourceBindings(schema);
43
- record(name, schema, await runStages(bindingsBeforePrompt(bindings), stageInput(name, schema, parsedFlags, bindings, options.prompter), state), resolved, errors, hardErrorFlags, options);
44
- }
45
- const interactiveConfigs = options.interactive !== void 0 ? options.interactive({ flags: resolved }) : void 0;
46
- for (const [name, schema] of Object.entries(flagSchemas)) {
47
- if (Object.hasOwn(resolved, name) || hardErrorFlags.has(name)) continue;
48
- const bindings = withPromptBinding(schema, sourceBindings(schema), effectivePromptConfig(name, schema, interactiveConfigs));
49
- record(name, schema, await runStages(bindingsFromPrompt(bindings), stageInput(name, schema, parsedFlags, bindings, options.prompter), state), resolved, errors, hardErrorFlags, options);
50
- if (Object.hasOwn(resolved, name) || hardErrorFlags.has(name)) continue;
51
- if (schema.kind === "array" && schema.presence !== "required") {
52
- resolved[name] = [];
53
- options.provenance[name] = { stage: "default" };
54
- continue;
55
- }
56
- if (schema.kind === "keyValue" && schema.presence !== "required") {
57
- resolved[name] = {};
58
- options.provenance[name] = { stage: "default" };
59
- continue;
60
- }
61
- if (schema.presence === "required") {
62
- const details = {
63
- flag: name,
64
- kind: schema.kind
65
- };
66
- if (schema.envVar !== void 0) details.envVar = schema.envVar;
67
- if (schema.configPath !== void 0) details.configPath = schema.configPath;
68
- errors.push(new ValidationError(`Missing required flag --${name}`, {
69
- code: "REQUIRED_FLAG",
70
- details,
71
- suggest: buildRequiredFlagSuggest(name, schema)
72
- }));
73
- continue;
74
- }
75
- resolved[name] = void 0;
76
- }
77
- for (const [name, schema] of Object.entries(flagSchemas)) {
78
- const value = Object.hasOwn(resolved, name) ? resolved[name] : void 0;
79
- const checks = flagValueSchema(schema).pathChecks;
80
- if (schema.kind === "array" && schema.unique && Array.isArray(value)) resolved[name] = [...dedupe(value)];
81
- if (checks === void 0 || options.stat === void 0) continue;
82
- const echo = echoesValue(Object.hasOwn(options.provenance, name) ? options.provenance[name] : void 0);
83
- for (const path of pathValuesOf(Object.hasOwn(resolved, name) ? resolved[name] : void 0)) {
84
- const violation = await validatePathChecks({
85
- kind: "flag",
86
- name
87
- }, path, checks, options.stat, options.mkdir, echo);
88
- if (violation !== void 0) errors.push(violation);
89
- }
90
- }
91
- if (isNonEmpty(errors)) throwAggregatedErrors(errors);
92
- return resolved;
93
- }
94
- /** Assemble what one flag contributes to its own resolution. */
95
- function stageInput(name, schema, parsedFlags, bindings, prompter) {
96
- const present = Object.hasOwn(parsedFlags, name);
97
- return {
98
- cli: readCliValue(present, present ? parsedFlags[name] : void 0, bindings),
99
- coerce: (binding, raw) => coerceValue(name, binding, raw, schema),
100
- finishCli: (value, stdinData, stdin) => finishCliFlagValue(name, schema, value, stdinData, stdin),
101
- runPrompt: async (binding) => prompter === void 0 ? {
102
- ok: false,
103
- error: void 0
104
- } : resolvePromptValueWithConfig(name, schema, binding, prompter)
105
- };
106
- }
107
- /** Apply one stage walk's outcome to the resolution state. */
108
- function record(name, schema, outcome, resolved, errors, hardErrorFlags, options) {
109
- if (outcome.kind === "error") {
110
- errors.push(outcome.error);
111
- hardErrorFlags.add(name);
112
- return;
113
- }
114
- if (outcome.kind === "absent") return;
115
- if (schema.deprecated !== void 0 && outcome.provenance.stage !== "default") options.deprecations.push({
116
- kind: "flag",
117
- name,
118
- message: schema.deprecated
119
- });
120
- resolved[name] = outcome.value;
121
- options.provenance[name] = outcome.provenance;
122
- }
123
- /**
124
- * Pick the prompt config this invocation uses for a flag.
125
- *
126
- * `.interactive()` returning `false` disables the prompt outright; any other
127
- * falsy value means "no override" and leaves the schema's own config in place.
128
- */
129
- function effectivePromptConfig(name, schema, interactiveConfigs) {
130
- const override = interactiveConfigs !== void 0 && Object.hasOwn(interactiveConfigs, name) ? interactiveConfigs[name] : void 0;
131
- if (override === false) return void 0;
132
- if (override === void 0 || override === null || override === 0 || override === "") return schema.prompt;
133
- return override;
134
- }
135
- /** Maps each flag kind to the prompt kinds that produce compatible values. */
136
- const COMPATIBLE_PROMPT_KINDS = {
137
- boolean: ["confirm"],
138
- string: ["input", "select"],
139
- number: ["input"],
140
- enum: ["select", "input"],
141
- array: ["multiselect"],
142
- custom: [
143
- "input",
144
- "select",
145
- "confirm",
146
- "multiselect"
147
- ],
148
- count: [],
149
- keyValue: []
150
- };
151
- /**
152
- * Word an incompatible prompt config for the surface that declared it.
153
- *
154
- * A kind with no compatible prompt at all is a different diagnostic from one
155
- * whose prompt is merely the wrong sort, so the empty list gets its own message
156
- * on both surfaces.
157
- *
158
- * @param subject - How the surface spells the input.
159
- * @param kind - The input's declared kind.
160
- * @param promptKind - The prompt kind the config asked for.
161
- * @param allowed - The prompt kinds that kind accepts.
162
- * @returns The error to report.
163
- * @internal
164
- */
165
- function promptCompatibilityError(subject, kind, promptKind, allowed) {
166
- const details = {
167
- ...subject.details,
168
- promptKind,
169
- allowed
170
- };
171
- const headline = `Prompt kind '${promptKind}' is not compatible with ${kind} ${subject.singular} ${subject.reference}.`;
172
- const first = allowed[0];
173
- if (first === void 0) return new ValidationError(`${headline} ${kind} ${subject.plural} are not promptable`, {
174
- code: "CONSTRAINT_VIOLATED",
175
- details,
176
- suggest: `Remove the prompt config for ${subject.reference}`
177
- });
178
- return new ValidationError(`${headline} Use '${first}' instead`, {
179
- code: "CONSTRAINT_VIOLATED",
180
- details,
181
- suggest: `Change the prompt to { kind: '${first}' } for ${subject.reference}`
182
- });
183
- }
184
- /**
185
- * Check whether a prompt kind is compatible with the flag's declared kind.
186
- *
187
- * @returns `undefined` when compatible, or a {@link ValidationError} with
188
- * code `'CONSTRAINT_VIOLATED'` and an actionable `suggest` message when not.
189
- * @internal
190
- */
191
- function validatePromptFlagCompatibility(flagName, flagKind, promptKind) {
192
- const allowed = COMPATIBLE_PROMPT_KINDS[flagKind];
193
- if (allowed.includes(promptKind)) return void 0;
194
- return promptCompatibilityError({
195
- reference: `--${flagName}`,
196
- singular: "flag",
197
- plural: "flags",
198
- details: {
199
- flag: flagName,
200
- flagKind
201
- }
202
- }, flagKind, promptKind, allowed);
203
- }
204
- /**
205
- * Validate prompt/flag compatibility, run the prompt engine, and coerce the result.
206
- *
207
- * Returns early with a {@link ValidationError} if the prompt kind is
208
- * incompatible with the flag kind (checked via {@link COMPATIBLE_PROMPT_KINDS}
209
- * before the prompter is invoked).
210
- * @internal
211
- */
212
- async function resolvePromptValueWithConfig(flagName, schema, binding, prompter) {
213
- const promptConfig = binding.prompt;
214
- const mismatch = validatePromptFlagCompatibility(flagName, schema.kind, promptConfig.kind);
215
- if (mismatch !== void 0) return {
216
- ok: false,
217
- error: mismatch
218
- };
219
- const resolvedConfig = resolvePromptConfig(promptConfig, valueEnumValues(flagValueSchema(schema)));
220
- const result = await prompter.promptOne(resolvedConfig);
221
- if (!result.answered) return {
222
- ok: false,
223
- error: void 0
224
- };
225
- if (promptConfig.kind === "input" && promptConfig.default === void 0 && typeof result.value === "string" && result.value.trim() === "") return {
226
- ok: false,
227
- error: void 0
228
- };
229
- return coerceValue(flagName, binding, result.value, schema);
230
- }
231
- /** Build a human-readable suggestion listing all available sources for a required flag. @internal */
232
- function buildRequiredFlagSuggest(name, schema) {
233
- const sources = [];
234
- const takesValue = schema.kind !== "boolean" && schema.kind !== "count";
235
- sources.push(`Provide --${name}${takesValue ? " <value>" : ""}`);
236
- const stdin = schema.stdin;
237
- if (stdin !== void 0) sources.push(stdin.when === "dash" ? `pass --${name} - to read stdin` : stdin.when === "missing" ? `pipe a value to stdin` : `pipe a value to stdin or pass --${name} -`);
238
- if (schema.envVar !== void 0) sources.push(`set ${schema.envVar}`);
239
- if (schema.configPath !== void 0) sources.push(`add ${schema.configPath} to config`);
240
- if (sources.length <= 1) return sources.join("");
241
- const rest = sources.slice(0, -1);
242
- const last = sources.slice(-1).join("");
243
- return sources.length === 2 ? `${rest.join("")} or ${last}` : `${rest.join(", ")}, or ${last}`;
244
- }
245
- //#endregion
246
- export { COMPATIBLE_PROMPT_KINDS, promptCompatibilityError, resolveFlags };