@kjanat/dreamcli 4.0.0-rc.3 → 4.0.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.
- package/README.md +5 -7
- package/dist/{runtime/adapter.d.mts → adapter-D0hbBNVB.d.mts} +2 -4
- package/dist/completion-D4mz6axB.mjs +6 -0
- package/dist/completion.d.mts +90 -0
- package/dist/completion.mjs +1 -0
- package/dist/config-B9ddC-Kb.mjs +1 -0
- package/dist/config.d.mts +2 -0
- package/dist/config.mjs +1 -0
- package/dist/core-Cp2w8vRq.mjs +17 -0
- package/dist/index-BziI2aKc.d.mts +5440 -0
- package/dist/index-DOfClfYR.d.mts +370 -0
- package/dist/index-DWsnGZlx.d.mts +831 -0
- package/dist/{core/cli/index.d.mts → index-DXROeDPC.d.mts} +116 -57
- package/dist/index-DndPmT8J.d.mts +275 -0
- package/dist/{core/json-schema/index.d.mts → index-DyoaS234.d.mts} +43 -34
- package/dist/index.d.mts +190 -41
- package/dist/index.mjs +1 -26
- package/dist/json-schema-C9SzZ7jY.mjs +52 -0
- package/dist/json-schema.d.mts +2 -0
- package/dist/json-schema.mjs +1 -0
- package/dist/package-json-BgE9YjjQ.mjs +3 -0
- package/dist/prompt.d.mts +48 -0
- package/dist/prompt.mjs +1 -0
- package/dist/rolldown-runtime-G4Kt5YOX.mjs +1 -0
- package/dist/runtime.d.mts +2 -6
- package/dist/runtime.mjs +1 -6
- package/dist/terminal-C8KTXjv5.mjs +6 -0
- package/dist/test-prompter-v__jT2yG.mjs +1 -0
- package/dist/testkit.d.mts +54 -6
- package/dist/testkit.mjs +1 -5
- package/dist/version.mjs +1 -7
- package/dreamcli.schema.json +697 -538
- package/package.json +29 -7
- package/skills/cli-creation/SKILL.md +16 -11
- package/CHANGELOG.md +0 -1116
- package/dist/core/cli/builtins.d.mts +0 -117
- package/dist/core/cli/builtins.mjs +0 -135
- package/dist/core/cli/compiled.d.mts +0 -66
- package/dist/core/cli/compiled.mjs +0 -76
- package/dist/core/cli/dispatch.d.mts +0 -115
- package/dist/core/cli/dispatch.mjs +0 -205
- package/dist/core/cli/help-links.d.mts +0 -27
- package/dist/core/cli/help-links.mjs +0 -41
- package/dist/core/cli/index.mjs +0 -1271
- package/dist/core/cli/planner.d.mts +0 -174
- package/dist/core/cli/planner.mjs +0 -323
- package/dist/core/cli/plugin.d.mts +0 -94
- package/dist/core/cli/plugin.mjs +0 -41
- package/dist/core/cli/propagate.d.mts +0 -39
- package/dist/core/cli/propagate.mjs +0 -57
- package/dist/core/cli/reserved-flags.d.mts +0 -19
- package/dist/core/cli/reserved-flags.mjs +0 -158
- package/dist/core/cli/root-help.d.mts +0 -53
- package/dist/core/cli/root-help.mjs +0 -221
- package/dist/core/cli/root-output-flags.d.mts +0 -74
- package/dist/core/cli/root-output-flags.mjs +0 -169
- package/dist/core/cli/root-surface.d.mts +0 -64
- package/dist/core/cli/root-surface.mjs +0 -28
- package/dist/core/cli/runtime-preflight.d.mts +0 -213
- package/dist/core/cli/runtime-preflight.mjs +0 -221
- package/dist/core/completion/index.d.mts +0 -76
- package/dist/core/completion/index.mjs +0 -90
- package/dist/core/completion/shells/bash.d.mts +0 -23
- package/dist/core/completion/shells/bash.mjs +0 -312
- package/dist/core/completion/shells/fish.d.mts +0 -19
- package/dist/core/completion/shells/fish.mjs +0 -164
- package/dist/core/completion/shells/powershell.d.mts +0 -13
- package/dist/core/completion/shells/powershell.mjs +0 -360
- package/dist/core/completion/shells/shared.d.mts +0 -164
- package/dist/core/completion/shells/shared.mjs +0 -147
- package/dist/core/completion/shells/zsh.d.mts +0 -23
- package/dist/core/completion/shells/zsh.mjs +0 -256
- package/dist/core/config/index.d.mts +0 -191
- package/dist/core/config/index.mjs +0 -285
- package/dist/core/config/package-json.d.mts +0 -179
- package/dist/core/config/package-json.mjs +0 -353
- package/dist/core/errors/index.d.mts +0 -125
- package/dist/core/errors/index.mjs +0 -87
- package/dist/core/execution/index.d.mts +0 -61
- package/dist/core/execution/index.mjs +0 -220
- package/dist/core/help/ansi.d.mts +0 -84
- package/dist/core/help/ansi.mjs +0 -121
- package/dist/core/help/index.d.mts +0 -149
- package/dist/core/help/index.mjs +0 -418
- package/dist/core/help/theme.d.mts +0 -86
- package/dist/core/help/theme.mjs +0 -69
- package/dist/core/json-schema/index.mjs +0 -1008
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +0 -274
- package/dist/core/json-schema/meta-descriptions.generated.mjs +0 -136
- package/dist/core/output/activity.d.mts +0 -193
- package/dist/core/output/activity.mjs +0 -452
- package/dist/core/output/bind.d.mts +0 -37
- package/dist/core/output/bind.mjs +0 -56
- package/dist/core/output/contracts.d.mts +0 -82
- package/dist/core/output/contracts.mjs +0 -57
- package/dist/core/output/display-value.d.mts +0 -19
- package/dist/core/output/display-value.mjs +0 -32
- package/dist/core/output/index.d.mts +0 -344
- package/dist/core/output/index.mjs +0 -514
- package/dist/core/output/renderers.d.mts +0 -45
- package/dist/core/output/renderers.mjs +0 -46
- package/dist/core/output/writer.d.mts +0 -39
- package/dist/core/output/writer.mjs +0 -12
- package/dist/core/parse/index.d.mts +0 -178
- package/dist/core/parse/index.mjs +0 -850
- package/dist/core/parse/occurrences.d.mts +0 -90
- package/dist/core/parse/occurrences.mjs +0 -114
- package/dist/core/prompt/index.d.mts +0 -213
- package/dist/core/prompt/index.mjs +0 -348
- package/dist/core/read-flags/index.d.mts +0 -150
- package/dist/core/read-flags/index.mjs +0 -217
- package/dist/core/resolve/args.d.mts +0 -39
- package/dist/core/resolve/args.mjs +0 -182
- package/dist/core/resolve/coerce.d.mts +0 -79
- package/dist/core/resolve/coerce.mjs +0 -900
- package/dist/core/resolve/config.d.mts +0 -10
- package/dist/core/resolve/config.mjs +0 -19
- package/dist/core/resolve/contracts.d.mts +0 -146
- package/dist/core/resolve/errors.d.mts +0 -10
- package/dist/core/resolve/errors.mjs +0 -148
- package/dist/core/resolve/flags.d.mts +0 -74
- package/dist/core/resolve/flags.mjs +0 -246
- package/dist/core/resolve/index.d.mts +0 -44
- package/dist/core/resolve/index.mjs +0 -123
- package/dist/core/resolve/path-checks.d.mts +0 -48
- package/dist/core/resolve/path-checks.mjs +0 -102
- package/dist/core/resolve/redaction.d.mts +0 -13
- package/dist/core/resolve/redaction.mjs +0 -14
- package/dist/core/resolve/stages.d.mts +0 -86
- package/dist/core/resolve/stages.mjs +0 -170
- package/dist/core/resolve/standard.d.mts +0 -26
- package/dist/core/resolve/standard.mjs +0 -212
- package/dist/core/schema/activity.d.mts +0 -189
- package/dist/core/schema/arg.d.mts +0 -1461
- package/dist/core/schema/arg.mjs +0 -1139
- package/dist/core/schema/brand.d.mts +0 -17
- package/dist/core/schema/cardinality.d.mts +0 -302
- package/dist/core/schema/cardinality.mjs +0 -514
- package/dist/core/schema/command.d.mts +0 -1132
- package/dist/core/schema/command.mjs +0 -999
- package/dist/core/schema/flag.d.mts +0 -1495
- package/dist/core/schema/flag.mjs +0 -1207
- package/dist/core/schema/index.d.mts +0 -15
- package/dist/core/schema/index.mjs +0 -10
- package/dist/core/schema/middleware.d.mts +0 -129
- package/dist/core/schema/middleware.mjs +0 -41
- package/dist/core/schema/number-constraints.d.mts +0 -96
- package/dist/core/schema/number-constraints.mjs +0 -60
- package/dist/core/schema/prompt.d.mts +0 -135
- package/dist/core/schema/provenance.d.mts +0 -99
- package/dist/core/schema/provenance.mjs +0 -28
- package/dist/core/schema/run.d.mts +0 -211
- package/dist/core/schema/source.d.mts +0 -180
- package/dist/core/schema/source.mjs +0 -206
- package/dist/core/schema/standard.d.mts +0 -100
- package/dist/core/schema/standard.mjs +0 -15
- package/dist/core/schema/stdin.d.mts +0 -97
- package/dist/core/schema/stdin.mjs +0 -91
- package/dist/core/schema/string-constraints.d.mts +0 -108
- package/dist/core/schema/string-constraints.mjs +0 -86
- package/dist/core/schema/value-parsers.d.mts +0 -150
- package/dist/core/schema/value-parsers.mjs +0 -160
- package/dist/core/schema/value.d.mts +0 -243
- package/dist/core/schema/value.mjs +0 -573
- package/dist/core/testkit/index.d.mts +0 -63
- package/dist/core/testkit/index.mjs +0 -102
- package/dist/runtime/adapter.mjs +0 -92
- package/dist/runtime/auto.d.mts +0 -25
- package/dist/runtime/auto.mjs +0 -45
- package/dist/runtime/deno.d.mts +0 -99
- package/dist/runtime/deno.mjs +0 -265
- package/dist/runtime/detect.d.mts +0 -86
- package/dist/runtime/detect.mjs +0 -45
- package/dist/runtime/index.d.mts +0 -6
- package/dist/runtime/node.d.mts +0 -71
- package/dist/runtime/node.mjs +0 -228
- package/dist/runtime/paths.d.mts +0 -31
- package/dist/runtime/paths.mjs +0 -48
- package/dist/strings.d.mts +0 -27
- package/dist/strings.mjs +0 -22
- package/examples/basic.ts +0 -37
- package/examples/flag-types.ts +0 -79
- package/examples/gh/package.json +0 -45
- package/examples/gh/src/commands/auth.ts +0 -66
- package/examples/gh/src/commands/issue.ts +0 -120
- package/examples/gh/src/commands/pr.ts +0 -125
- package/examples/gh/src/data/issues.yaml +0 -5
- package/examples/gh/src/data/issues.yaml.d.ts +0 -17
- package/examples/gh/src/data/pull-requests.yaml +0 -7
- package/examples/gh/src/data/pull-requests.yaml.d.ts +0 -18
- package/examples/gh/src/docs.ts +0 -11
- package/examples/gh/src/lib/auth.ts +0 -37
- package/examples/gh/src/lib/utils.ts +0 -17
- package/examples/gh/src/main.test.ts +0 -307
- package/examples/gh/src/main.ts +0 -46
- package/examples/help-config.ts +0 -43
- package/examples/interactive.ts +0 -67
- package/examples/json-mode.ts +0 -95
- package/examples/middleware.ts +0 -71
- package/examples/multi-command.ts +0 -66
- package/examples/output-extras.ts +0 -46
- package/examples/parser-control.ts +0 -40
- package/examples/pwsh-demo/README.md +0 -40
- package/examples/pwsh-demo/package.json +0 -41
- package/examples/pwsh-demo/pwsh-demo.cmd +0 -3
- package/examples/pwsh-demo/smoke-powershell.ps1 +0 -218
- package/examples/pwsh-demo/src/main.test.ts +0 -45
- package/examples/pwsh-demo/src/main.ts +0 -140
- package/examples/spinner-progress.ts +0 -49
- package/examples/standard-schema.ts +0 -45
- package/examples/testing.ts +0 -147
- 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 };
|