@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,211 +0,0 @@
1
- import { BuiltinsConfig } from "../cli/builtins.mjs";
2
- import { CLIError } from "../errors/index.mjs";
3
- import { ActivityEvent } from "./activity.mjs";
4
- import { Verbosity } from "../output/contracts.mjs";
5
- import { CommandMeta, CommandSchema, Out } from "./command.mjs";
6
- import { HelpOptions } from "../help/index.mjs";
7
- import { CapturedOutput } from "../output/index.mjs";
8
- import { PromptEngine, TestAnswer } from "../prompt/index.mjs";
9
- import { ParseOptions } from "../parse/index.mjs";
10
- import { CLIPlugin } from "../cli/plugin.mjs";
11
- //#region src/core/schema/run.d.ts
12
- /**
13
- * Options accepted by `runCommand()` and internal command execution paths.
14
- *
15
- * Every field is optional — sensible defaults are applied. This is the
16
- * primary process-free execution seam: inject env, config, prompt I/O, and
17
- * dispatch-layer metadata without touching process state.
18
- */
19
- export interface RunOptions {
20
- /**
21
- * Environment variables for flag and arg resolution.
22
- *
23
- * Inputs with `.env('VAR')` configured resolve from this record when CLI
24
- * and stdin produce nothing
25
- * (CLI → stdin → env → config → prompt → default).
26
- */
27
- readonly env?: Readonly<Record<string, string | undefined>>;
28
- /**
29
- * Configuration object for flag and arg resolution.
30
- *
31
- * Inputs with `.config('path')` configured resolve from this record when
32
- * CLI, stdin, and env produce nothing
33
- * (CLI → stdin → env → config → prompt → default).
34
- * Config is plain JSON, so file loading is the caller's responsibility.
35
- */
36
- readonly config?: Readonly<Record<string, unknown>>;
37
- /**
38
- * Full stdin contents for flags and args configured with `.stdin()`.
39
- *
40
- * Lets tests inject piped input without a runtime adapter.
41
- */
42
- readonly stdinData?: string | null;
43
- /**
44
- * Prompt engine for interactive flag and arg resolution.
45
- *
46
- * When provided, inputs with `.prompt()` configured that have no value
47
- * after CLI, stdin, env, and config resolution are prompted interactively.
48
- *
49
- * When absent (and `answers` is also absent), prompting is skipped
50
- * and resolution falls through to default/required.
51
- *
52
- * Takes precedence over `answers` when both are provided.
53
- */
54
- readonly prompter?: PromptEngine;
55
- /**
56
- * Pre-configured prompt answers for testing convenience.
57
- *
58
- * When provided, a test prompter is created from these answers via
59
- * `createTestPrompter(answers)`. Each entry is consumed in order —
60
- * use `PROMPT_CANCEL` to simulate cancellation.
61
- *
62
- * Ignored when an explicit `prompter` is provided.
63
- */
64
- readonly answers?: readonly TestAnswer[];
65
- /**
66
- * Filesystem probe for `flag.path()` and `arg.path()` checks: reports what
67
- * exists at a path (`'file'`, `'directory'`, or `null` for nothing).
68
- *
69
- * `CLIBuilder.run()` supplies the runtime adapter's probe automatically.
70
- * When absent (process-free `.execute()` / `runCommand()` without an
71
- * override), path checks are skipped.
72
- */
73
- readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
74
- /**
75
- * Recursive directory creation for `flag.path()` and `arg.path()` `create`
76
- * checks.
77
- *
78
- * `CLIBuilder.run()` supplies the runtime adapter's implementation
79
- * automatically. When absent, missing paths are not created.
80
- */
81
- readonly mkdir?: (path: string) => Promise<void>;
82
- /**
83
- * Verbosity level for the output channel.
84
- * @defaultValue `'normal'`
85
- */
86
- readonly verbosity?: Verbosity;
87
- /**
88
- * Enable JSON output mode.
89
- *
90
- * When `true`, `log` and `info` messages are redirected to stderr
91
- * so that stdout is reserved exclusively for structured {@linkcode Out.json | json()} output.
92
- * Framework-rendered errors are emitted as structured JSON to stdout.
93
- *
94
- * @defaultValue `false`
95
- */
96
- readonly jsonMode?: boolean;
97
- /**
98
- * Whether stdout is connected to a TTY.
99
- *
100
- * Handlers can check {@linkcode Out.isTTY | out.isTTY} to decide whether to emit decorative
101
- * output (spinners, progress bars, ANSI codes). Defaults to `false`
102
- * (safe default for tests — non-TTY until proven otherwise).
103
- *
104
- * @defaultValue `false`
105
- */
106
- readonly isTTY?: boolean;
107
- /**
108
- * Help formatting options (width, binName).
109
- * Used when `--help` is detected.
110
- */
111
- readonly help?: HelpOptions;
112
- /**
113
- * Flag-parsing behavior settings.
114
- *
115
- * `caseParity` accepts the kebab↔camel counterpart spelling of each flag
116
- * name/alias (`--doThis` for `do-this`, and vice versa). The CLI layer
117
- * threads `cli(name, { flags })` settings here automatically.
118
- *
119
- * @defaultValue `{ caseParity: true }`
120
- */
121
- readonly flags?: ParseOptions;
122
- }
123
- /**
124
- * Execution options threaded between the CLI dispatch layer, the shared
125
- * executor, and the testkit. Extends the public {@linkcode RunOptions} with
126
- * fields the framework populates itself.
127
- *
128
- * @internal
129
- */
130
- export interface InternalRunOptions extends RunOptions {
131
- /**
132
- * Output channel override used by live CLI execution.
133
- *
134
- * `CLIBuilder.run()` passes a real output channel so activity renders to
135
- * the terminal instead of being captured.
136
- */
137
- readonly out?: Out;
138
- /**
139
- * Capture buffers override paired with `out`.
140
- *
141
- * When omitted, `runCommand()` creates empty buffers for the returned
142
- * {@linkcode RunResult} while writing directly to the provided `out`.
143
- */
144
- readonly captured?: CapturedOutput;
145
- /**
146
- * Command schema with propagated flags merged in.
147
- *
148
- * When provided, `runCommandInternal()` uses it for parsing and resolution
149
- * instead of `cmd.schema`. CLI dispatch passes its merged schema straight to
150
- * the shared executor and leaves this field unset.
151
- */
152
- readonly mergedSchema?: CommandSchema;
153
- /**
154
- * CLI program metadata passed to action handlers and middleware.
155
- *
156
- * When provided (by CLI dispatch layer), handlers receive this as `meta`.
157
- * When absent (standalone `runCommand()`), a minimal meta is constructed
158
- * from the command's own schema.
159
- */
160
- readonly meta?: CommandMeta;
161
- /** CLI plugins registered on the parent `CLIBuilder`. */
162
- readonly plugins?: readonly CLIPlugin[];
163
- /**
164
- * Built-in flag state from the CLI schema.
165
- *
166
- * `help: 'off'` releases the command-level `--help`/`-h` short-circuit so a
167
- * command's own `help` flag parses. Absent means every built-in is on.
168
- */
169
- readonly builtins?: BuiltinsConfig;
170
- }
171
- /**
172
- * Structured result from {@linkcode runCommand}.
173
- *
174
- * Contains the exit code, captured stdout/stderr output, recorded
175
- * {@linkcode ActivityEvent | activity events}, and an `error` field.
176
- * `error` is `undefined` when execution completed without throwing, even if
177
- * the handler requested a non-zero status via {@linkcode Out.setExitCode}.
178
- *
179
- * @example
180
- * ```ts
181
- * const result = await runCommand(greetCmd, ['World']);
182
- *
183
- * expect(result.exitCode).toBe(0);
184
- * expect(result.stdout).toContain('Hello, World!');
185
- * expect(result.error).toBeUndefined();
186
- * ```
187
- */
188
- export interface RunResult {
189
- /** Process exit code. 0 = success. */
190
- readonly exitCode: number;
191
- /** Captured stdout lines (from `out.log` and `out.info`). */
192
- readonly stdout: readonly string[];
193
- /** Captured stderr lines (from `out.warn` and `out.error`). */
194
- readonly stderr: readonly string[];
195
- /**
196
- * Captured spinner and progress lifecycle events.
197
- *
198
- * Recorded separately from stdout/stderr — handlers that call
199
- * {@linkcode Out.spinner | out.spinner()} or {@linkcode Out.progress | out.progress()} produce events here, enabling
200
- * targeted assertions on activity lifecycle without parsing text.
201
- */
202
- readonly activity: readonly ActivityEvent[];
203
- /**
204
- * The error that caused a failure, or `undefined` when execution completed.
205
- * A non-zero `exitCode` can still have no error when a handler calls
206
- * {@linkcode Out.setExitCode}. {@linkcode CLIError} instances are preserved;
207
- * unknown errors are wrapped.
208
- */
209
- readonly error: CLIError | undefined;
210
- }
211
- //#endregion
@@ -1,180 +0,0 @@
1
- import { PromptConfig } from "./prompt.mjs";
2
- import { StdinBinding, StdinConsume, StdinWhen } from "./stdin.mjs";
3
- import { FlagSchema } from "./flag.mjs";
4
- import { SplitPolicy } from "./cardinality.mjs";
5
- import { ArgSchema } from "./arg.mjs";
6
- //#region src/core/schema/source.d.ts
7
- /**
8
- * Ordered resolution stages, highest precedence first.
9
- *
10
- * Both surfaces walk this one list. An explicit `-` is CLI-sourced with bytes
11
- * from stdin, so it lands on `'cli'`; the `'stdin'` stage is the implicit
12
- * fallback an absent CLI value takes before env.
13
- */
14
- declare const RESOLUTION_ORDER: readonly ["cli", "stdin", "env", "config", "prompt", "default"];
15
- /** One stage of {@link RESOLUTION_ORDER}. */
16
- type ResolutionStage = (typeof RESOLUTION_ORDER)[number];
17
- /**
18
- * One declared source of a flag or an arg.
19
- *
20
- * Every stage that carries raw text also carries the {@link SplitPolicy} that
21
- * text decodes under, so a collection's per-source splitting is read off the
22
- * binding of the stage that produced the value. A declared default is already
23
- * the typed value and has nothing to split.
24
- */
25
- type SourceBinding = {
26
- readonly stage: 'cli';
27
- readonly split: SplitPolicy;
28
- } | {
29
- readonly stage: 'stdin';
30
- readonly when: StdinWhen;
31
- readonly consume: StdinConsume;
32
- readonly trim: boolean;
33
- readonly split: SplitPolicy;
34
- } | {
35
- readonly stage: 'env';
36
- readonly envVar: string;
37
- readonly split: SplitPolicy;
38
- } | {
39
- readonly stage: 'config';
40
- readonly configPath: string;
41
- readonly split: SplitPolicy;
42
- } | {
43
- readonly stage: 'prompt';
44
- readonly prompt: PromptConfig;
45
- readonly split: SplitPolicy;
46
- } | {
47
- readonly stage: 'default';
48
- readonly defaultValue: unknown;
49
- };
50
- /** The stdin source of an input, once {@link sourceBindings} has projected it. */
51
- type StdinSourceBinding = Extract<SourceBinding, {
52
- readonly stage: 'stdin';
53
- }>;
54
- /** The interactive source of an input, once {@link sourceBindings} has projected it. */
55
- type PromptSourceBinding = Extract<SourceBinding, {
56
- readonly stage: 'prompt';
57
- }>;
58
- /**
59
- * The sources whose raw values a stage decodes.
60
- *
61
- * A CLI token is decoded at the parse boundary, and a default never decodes at
62
- * all, so neither reaches the resolver's coercion pass.
63
- */
64
- type DecodedSourceBinding = Exclude<SourceBinding, {
65
- readonly stage: 'cli';
66
- } | {
67
- readonly stage: 'default';
68
- }>;
69
- /**
70
- * Project a flag or arg schema onto its source axis.
71
- *
72
- * Every input accepts CLI input, so the list always opens with `'cli'`. The
73
- * remaining entries appear in {@link RESOLUTION_ORDER} order, and only for the
74
- * sources the schema actually declares. The resolver walks this list, so a
75
- * source the list omits is a source no stage can produce.
76
- *
77
- * A config value is native when it is an array or an object, and a config
78
- * string decodes under the environment policy, which is the delimited form a
79
- * user would have typed. A prompt answer reads the same way.
80
- *
81
- * @param schema - The flag or arg schema to read.
82
- * @returns The declared sources, ordered by precedence.
83
- */
84
- declare function sourceBindings(schema: FlagSchema | ArgSchema): readonly SourceBinding[];
85
- /**
86
- * The stdin source of an input, or `undefined` when it declares none.
87
- *
88
- * @param bindings - One input's source list.
89
- * @returns The stdin binding, when the list carries one.
90
- */
91
- declare function stdinBindingOf(bindings: readonly SourceBinding[]): StdinSourceBinding | undefined;
92
- /**
93
- * The bindings an interactive resolver has not yet had a say in.
94
- *
95
- * @param bindings - One input's source list.
96
- * @returns The entries ranked before `'prompt'`.
97
- */
98
- declare function bindingsBeforePrompt(bindings: readonly SourceBinding[]): readonly SourceBinding[];
99
- /**
100
- * The bindings left once an interactive resolver has run.
101
- *
102
- * @param bindings - One input's source list.
103
- * @returns The entries ranked at or after `'prompt'`.
104
- */
105
- declare function bindingsFromPrompt(bindings: readonly SourceBinding[]): readonly SourceBinding[];
106
- /**
107
- * Replace the prompt binding with the config this invocation actually uses.
108
- *
109
- * `.interactive()` may hand a prompt to an input that declares none, or take
110
- * away the one it declares, so the effective list is per invocation rather than
111
- * per schema.
112
- *
113
- * @param schema - The flag or arg the list belongs to, read for its splitting.
114
- * @param bindings - One input's source list.
115
- * @param prompt - The prompt config to use, or `undefined` for no prompt.
116
- * @returns The list with its prompt binding set to `prompt`.
117
- */
118
- declare function withPromptBinding(schema: FlagSchema | ArgSchema, bindings: readonly SourceBinding[], prompt: PromptConfig | undefined): readonly SourceBinding[];
119
- /** One stdin-enabled input of a command, named by the surface that declares it. */
120
- interface StdinConsumer {
121
- /** Which surface declares the input. */
122
- readonly kind: 'flag' | 'arg';
123
- /** Canonical flag name or positional arg name. */
124
- readonly name: string;
125
- /** The input's stdin axis. */
126
- readonly stdin: StdinBinding;
127
- }
128
- /**
129
- * List the stdin consumers declared across a command's flags and args.
130
- *
131
- * @param flags - The command's flag schemas keyed by name.
132
- * @param args - The command's positional entries in declaration order.
133
- * @returns Every stdin-enabled input, flags first, then args in declaration order.
134
- */
135
- declare function stdinConsumers(flags: Readonly<Record<string, FlagSchema>>, args: readonly {
136
- readonly name: string;
137
- readonly schema: ArgSchema;
138
- }[]): readonly StdinConsumer[];
139
- /** How a stdin consumer is spelled on the command line: `--out` or `<out>`. */
140
- declare function stdinConsumerReference(consumer: Pick<StdinConsumer, 'kind' | 'name'>): string;
141
- /** What a parser produced for one command, read structurally. */
142
- interface ParsedInputs {
143
- /** Flag values keyed by canonical flag name. */
144
- readonly flags: Readonly<Record<string, unknown>>;
145
- /** Positional values keyed by arg name. */
146
- readonly args: Readonly<Record<string, unknown>>;
147
- }
148
- /**
149
- * Whether this invocation will actually select a stdin source.
150
- *
151
- * A `'dash'` binding fires when its token is `-`. A `'missing'` binding fires
152
- * when argv left the input absent; env, config, prompt, and default do not
153
- * suppress it, because the stdin fallback outranks all four. Callers use this
154
- * to decide whether reading the stream is warranted at all.
155
- *
156
- * @param flags - Declared flags keyed by canonical name.
157
- * @param args - Declared positionals in CLI order.
158
- * @param parsed - What the parser read off argv.
159
- * @returns `true` when at least one input would read stdin.
160
- */
161
- declare function invocationSelectsStdin(flags: Readonly<Record<string, FlagSchema>>, args: readonly {
162
- readonly name: string;
163
- readonly schema: ArgSchema;
164
- }[], parsed: ParsedInputs): boolean;
165
- /**
166
- * Whether a variadic arg's parsed value means its tail collected nothing.
167
- *
168
- * A variadic arg always has a key in the parser's record, and an empty list is
169
- * how it spells an empty tail, so an input that reads stdin when missing is
170
- * still missing here.
171
- *
172
- * @param schema - The positional's schema.
173
- * @param value - What the parser produced for it.
174
- * @returns `true` when the tail took no token.
175
- */
176
- declare function argCollectedNothing(schema: ArgSchema, value: unknown): boolean;
177
- /** The stdin selector, which names a source rather than a value. */
178
- declare const STDIN_SENTINEL = "-";
179
- //#endregion
180
- export { type DecodedSourceBinding, type ParsedInputs, type PromptSourceBinding, RESOLUTION_ORDER, type ResolutionStage, STDIN_SENTINEL, type SourceBinding, type StdinConsumer, type StdinSourceBinding, argCollectedNothing, bindingsBeforePrompt, bindingsFromPrompt, invocationSelectsStdin, sourceBindings, stdinBindingOf, stdinConsumerReference, stdinConsumers, withPromptBinding };
@@ -1,206 +0,0 @@
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 };