@kjanat/dreamcli 3.0.0-rc.1 → 3.0.0-rc.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +26 -1
- package/dist/core/cli/dispatch.mjs +214 -1
- package/dist/core/cli/help-links.mjs +41 -1
- package/dist/core/cli/index.mjs +901 -1
- package/dist/core/cli/planner.mjs +300 -1
- package/dist/core/cli/plugin.mjs +41 -1
- package/dist/core/cli/propagate.mjs +57 -1
- package/dist/core/cli/root-help.mjs +208 -4
- package/dist/core/cli/root-surface.mjs +27 -1
- package/dist/core/cli/runtime-preflight.mjs +168 -1
- package/dist/core/completion/index.mjs +90 -1
- package/dist/core/completion/shells/bash.mjs +304 -3
- package/dist/core/completion/shells/fish.mjs +159 -2
- package/dist/core/completion/shells/powershell.mjs +353 -2
- package/dist/core/completion/shells/shared.mjs +154 -1
- package/dist/core/completion/shells/zsh.mjs +244 -2
- package/dist/core/config/index.mjs +246 -1
- package/dist/core/config/package-json.mjs +385 -3
- package/dist/core/errors/index.mjs +87 -1
- package/dist/core/execution/index.mjs +189 -1
- package/dist/core/help/ansi.mjs +122 -2
- package/dist/core/help/index.mjs +329 -7
- package/dist/core/json-schema/index.mjs +487 -9
- package/dist/core/json-schema/meta-descriptions.generated.mjs +93 -28
- package/dist/core/output/activity.mjs +452 -1
- package/dist/core/output/bind.mjs +56 -1
- package/dist/core/output/contracts.mjs +57 -1
- package/dist/core/output/display-value.mjs +32 -1
- package/dist/core/output/index.d.mts +21 -0
- package/dist/core/output/index.mjs +442 -2
- package/dist/core/output/renderers.mjs +46 -1
- package/dist/core/output/writer.mjs +12 -1
- package/dist/core/parse/index.mjs +555 -1
- package/dist/core/prompt/index.d.mts +0 -1
- package/dist/core/prompt/index.mjs +348 -6
- package/dist/core/resolve/args.mjs +105 -1
- package/dist/core/resolve/coerce.mjs +279 -1
- package/dist/core/resolve/config.mjs +19 -1
- package/dist/core/resolve/errors.mjs +140 -2
- package/dist/core/resolve/flags.mjs +196 -1
- package/dist/core/resolve/index.mjs +85 -1
- package/dist/core/resolve/property.d.mts +0 -1
- package/dist/core/resolve/property.mjs +45 -1
- package/dist/core/schema/arg.mjs +463 -1
- package/dist/core/schema/command.d.mts +18 -0
- package/dist/core/schema/command.mjs +712 -1
- package/dist/core/schema/flag.mjs +453 -1
- package/dist/core/schema/middleware.mjs +41 -1
- package/dist/core/schema/number-constraints.mjs +60 -1
- package/dist/core/schema-dsl/runtime.mjs +271 -2
- package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
- package/dist/core/testkit/index.mjs +83 -1
- package/dist/index.d.mts +2 -1
- package/dist/index.mjs +22 -1
- package/dist/runtime/adapter.mjs +82 -1
- package/dist/runtime/auto.mjs +46 -1
- package/dist/runtime/bun.mjs +28 -1
- package/dist/runtime/deno.mjs +217 -2
- package/dist/runtime/detect.mjs +45 -1
- package/dist/runtime/node.mjs +169 -2
- package/dist/runtime/paths.mjs +48 -1
- package/dist/runtime.mjs +7 -1
- package/dist/strings.mjs +22 -1
- package/dist/testkit.mjs +5 -1
- package/dist/version.mjs +7 -1
- package/package.json +17 -26
- package/src/core/cli/dispatch.ts +0 -355
- package/src/core/cli/help-links.ts +0 -82
- package/src/core/cli/index.ts +0 -1614
- package/src/core/cli/planner.ts +0 -656
- package/src/core/cli/plugin.ts +0 -117
- package/src/core/cli/propagate.ts +0 -97
- package/src/core/cli/root-help.ts +0 -342
- package/src/core/cli/root-surface.ts +0 -87
- package/src/core/cli/runtime-preflight.ts +0 -456
- package/src/core/completion/index.ts +0 -138
- package/src/core/completion/shells/bash.ts +0 -459
- package/src/core/completion/shells/fish.ts +0 -259
- package/src/core/completion/shells/powershell.ts +0 -439
- package/src/core/completion/shells/shared.ts +0 -310
- package/src/core/completion/shells/zsh.ts +0 -381
- package/src/core/config/index.ts +0 -417
- package/src/core/config/package-json.ts +0 -560
- package/src/core/errors/index.ts +0 -193
- package/src/core/execution/index.ts +0 -265
- package/src/core/help/ansi.ts +0 -144
- package/src/core/help/index.ts +0 -563
- package/src/core/json-schema/index.ts +0 -910
- package/src/core/json-schema/meta-descriptions.generated.ts +0 -202
- package/src/core/output/activity.ts +0 -575
- package/src/core/output/bind.ts +0 -59
- package/src/core/output/contracts.ts +0 -194
- package/src/core/output/display-value.ts +0 -48
- package/src/core/output/index.ts +0 -704
- package/src/core/output/renderers.ts +0 -125
- package/src/core/output/writer.ts +0 -46
- package/src/core/parse/index.ts +0 -742
- package/src/core/prompt/index.ts +0 -623
- package/src/core/resolve/args.ts +0 -144
- package/src/core/resolve/coerce.ts +0 -500
- package/src/core/resolve/config.ts +0 -26
- package/src/core/resolve/contracts.ts +0 -135
- package/src/core/resolve/errors.ts +0 -227
- package/src/core/resolve/flags.ts +0 -269
- package/src/core/resolve/index.ts +0 -108
- package/src/core/resolve/property.ts +0 -99
- package/src/core/schema/activity.ts +0 -240
- package/src/core/schema/arg.ts +0 -841
- package/src/core/schema/command.ts +0 -1500
- package/src/core/schema/flag.ts +0 -917
- package/src/core/schema/index.ts +0 -96
- package/src/core/schema/middleware.ts +0 -171
- package/src/core/schema/number-constraints.ts +0 -153
- package/src/core/schema/prompt.ts +0 -171
- package/src/core/schema/run.ts +0 -198
- package/src/core/schema-dsl/index.ts +0 -109
- package/src/core/schema-dsl/parse.ts +0 -262
- package/src/core/schema-dsl/runtime.ts +0 -609
- package/src/core/schema-dsl/to-json-schema.ts +0 -102
- package/src/core/testkit/index.ts +0 -147
- package/src/index.ts +0 -181
- package/src/runtime/adapter.ts +0 -303
- package/src/runtime/auto.ts +0 -86
- package/src/runtime/bun.ts +0 -48
- package/src/runtime/deno.ts +0 -367
- package/src/runtime/detect.ts +0 -105
- package/src/runtime/index.ts +0 -21
- package/src/runtime/node-builtins.d.ts +0 -27
- package/src/runtime/node.ts +0 -289
- package/src/runtime/paths.ts +0 -64
- package/src/runtime/support.ts +0 -77
- package/src/runtime.ts +0 -31
- package/src/schema.ts +0 -16
- package/src/strings.ts +0 -34
- package/src/testkit.ts +0 -25
- package/src/version.ts +0 -20
|
@@ -1,135 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Internal resolver contract for precedence, diagnostics, and I/O shape.
|
|
3
|
-
*
|
|
4
|
-
* Captures the stable seam between parsed command input and resolved command
|
|
5
|
-
* values before the larger resolver module is split by concern.
|
|
6
|
-
*
|
|
7
|
-
* @module dreamcli/core/resolve/contracts
|
|
8
|
-
* @internal
|
|
9
|
-
*/
|
|
10
|
-
|
|
11
|
-
import type { ParseResult } from '#internals/core/parse/index.ts';
|
|
12
|
-
import type { PromptEngine } from '#internals/core/prompt/index.ts';
|
|
13
|
-
import type { CommandSchema } from '#internals/core/schema/index.ts';
|
|
14
|
-
|
|
15
|
-
/** Ordered flag resolution stages owned by the resolver. */
|
|
16
|
-
const FLAG_RESOLUTION_ORDER = ['cli', 'env', 'config', 'prompt', 'default'] as const;
|
|
17
|
-
|
|
18
|
-
/** Ordered arg resolution stages owned by the resolver. */
|
|
19
|
-
const ARG_RESOLUTION_ORDER = ['cli', 'stdin', 'env', 'default'] as const;
|
|
20
|
-
|
|
21
|
-
/** Stable flag-source labels for precedence and diagnostics. */
|
|
22
|
-
type FlagResolutionStage = (typeof FLAG_RESOLUTION_ORDER)[number];
|
|
23
|
-
|
|
24
|
-
/** Stable arg-source labels for precedence and diagnostics. */
|
|
25
|
-
type ArgResolutionStage = (typeof ARG_RESOLUTION_ORDER)[number];
|
|
26
|
-
|
|
27
|
-
/**
|
|
28
|
-
* Source-aware diagnostic context for flag resolution failures.
|
|
29
|
-
*
|
|
30
|
-
* CLI/default failures currently surface as missing-value validation errors,
|
|
31
|
-
* so only env/config/prompt need explicit source payloads here.
|
|
32
|
-
*/
|
|
33
|
-
type FlagDiagnosticSource =
|
|
34
|
-
| { readonly kind: 'env'; readonly envVar: string }
|
|
35
|
-
| { readonly kind: 'config'; readonly configPath: string }
|
|
36
|
-
| { readonly kind: 'prompt' };
|
|
37
|
-
|
|
38
|
-
/** Source-aware diagnostic context for arg resolution failures. */
|
|
39
|
-
type ArgDiagnosticSource =
|
|
40
|
-
| { readonly kind: 'env'; readonly envVar: string }
|
|
41
|
-
| { readonly kind: 'stdin' };
|
|
42
|
-
|
|
43
|
-
/**
|
|
44
|
-
* External state the resolver may consult after parsing.
|
|
45
|
-
*
|
|
46
|
-
* The resolver never reaches into `process`, files, or terminal APIs directly;
|
|
47
|
-
* callers inject those facts through this contract.
|
|
48
|
-
*/
|
|
49
|
-
interface ResolveOptions {
|
|
50
|
-
/** Pre-read stdin content, or `null` when stdin was not piped. */
|
|
51
|
-
readonly stdinData?: string | null;
|
|
52
|
-
/** Environment variable snapshot injected by the caller. */
|
|
53
|
-
readonly env?: Readonly<Record<string, string | undefined>>;
|
|
54
|
-
/** Parsed config file contents keyed by dotted path segments. */
|
|
55
|
-
readonly config?: Readonly<Record<string, unknown>>;
|
|
56
|
-
/** Interactive prompt engine; absent in non-TTY / CI contexts. */
|
|
57
|
-
readonly prompter?: PromptEngine;
|
|
58
|
-
}
|
|
59
|
-
|
|
60
|
-
/** Structured deprecation notice emitted for explicitly sourced values. */
|
|
61
|
-
interface DeprecationWarning {
|
|
62
|
-
/** Whether this deprecation targets a flag or a positional arg. */
|
|
63
|
-
readonly kind: 'flag' | 'arg';
|
|
64
|
-
/** Name of the deprecated flag or arg. */
|
|
65
|
-
readonly name: string;
|
|
66
|
-
/** Custom deprecation message, or `true` for the generic warning. */
|
|
67
|
-
readonly message: string | true;
|
|
68
|
-
}
|
|
69
|
-
|
|
70
|
-
/** Fully resolved command input handed to the executor layer. */
|
|
71
|
-
interface ResolveResult {
|
|
72
|
-
/** Fully resolved flag values keyed by flag name. */
|
|
73
|
-
readonly flags: Readonly<Record<string, unknown>>;
|
|
74
|
-
/** Fully resolved positional arg values keyed by arg name. */
|
|
75
|
-
readonly args: Readonly<Record<string, unknown>>;
|
|
76
|
-
/** Deprecation notices collected during resolution (may be empty). */
|
|
77
|
-
readonly deprecations: readonly DeprecationWarning[];
|
|
78
|
-
}
|
|
79
|
-
|
|
80
|
-
/** Explicit invocation boundary between parser output and resolved values. */
|
|
81
|
-
interface ResolverInvocation {
|
|
82
|
-
/** Command schema that declares flags, args, and resolution metadata. */
|
|
83
|
-
readonly schema: CommandSchema;
|
|
84
|
-
/** Raw parse result from the tokenizer/parser layer. */
|
|
85
|
-
readonly parsed: ParseResult;
|
|
86
|
-
/** Optional external state (env, config, stdin, prompter). */
|
|
87
|
-
readonly options?: ResolveOptions;
|
|
88
|
-
}
|
|
89
|
-
|
|
90
|
-
/**
|
|
91
|
-
* Stable resolver facts the re-foundation workstream is treating as contract.
|
|
92
|
-
*
|
|
93
|
-
* These are intended to anchor focused contract tests before larger module
|
|
94
|
-
* extraction and diagnostic redesign work lands.
|
|
95
|
-
*/
|
|
96
|
-
interface ResolverContract {
|
|
97
|
-
/** Ordered stages for flag resolution: cli -> env -> config -> prompt -> default. */
|
|
98
|
-
readonly flagPrecedence: readonly FlagResolutionStage[];
|
|
99
|
-
/** Ordered stages for arg resolution: cli -> stdin -> env -> default. */
|
|
100
|
-
readonly argPrecedence: readonly ArgResolutionStage[];
|
|
101
|
-
/** Prompt stage runs only after env and config have been attempted. */
|
|
102
|
-
readonly promptRunsAfterFlagConfig: true;
|
|
103
|
-
/** All validation errors are collected before throwing a single aggregate. */
|
|
104
|
-
readonly aggregatesValidationErrors: true;
|
|
105
|
-
/** Aggregate error details include per-issue structured summaries. */
|
|
106
|
-
readonly aggregateDiagnosticsIncludePerIssueSummary: true;
|
|
107
|
-
/** A coercion failure at env/config stops fallback to later stages for that flag. */
|
|
108
|
-
readonly hardCoercionErrorsStopFallback: true;
|
|
109
|
-
/** Deprecation warnings are emitted only when a value was actually sourced. */
|
|
110
|
-
readonly collectsDeprecationsFromExplicitSources: true;
|
|
111
|
-
}
|
|
112
|
-
|
|
113
|
-
/** Runtime-accessible resolution contract — documents the resolver's invariants for tests and diagnostics. */
|
|
114
|
-
const resolverContract = {
|
|
115
|
-
flagPrecedence: FLAG_RESOLUTION_ORDER,
|
|
116
|
-
argPrecedence: ARG_RESOLUTION_ORDER,
|
|
117
|
-
promptRunsAfterFlagConfig: true,
|
|
118
|
-
aggregatesValidationErrors: true,
|
|
119
|
-
aggregateDiagnosticsIncludePerIssueSummary: true,
|
|
120
|
-
hardCoercionErrorsStopFallback: true,
|
|
121
|
-
collectsDeprecationsFromExplicitSources: true,
|
|
122
|
-
} satisfies ResolverContract;
|
|
123
|
-
|
|
124
|
-
export type {
|
|
125
|
-
ArgDiagnosticSource,
|
|
126
|
-
ArgResolutionStage,
|
|
127
|
-
DeprecationWarning,
|
|
128
|
-
FlagDiagnosticSource,
|
|
129
|
-
FlagResolutionStage,
|
|
130
|
-
ResolveOptions,
|
|
131
|
-
ResolveResult,
|
|
132
|
-
ResolverContract,
|
|
133
|
-
ResolverInvocation,
|
|
134
|
-
};
|
|
135
|
-
export { ARG_RESOLUTION_ORDER, FLAG_RESOLUTION_ORDER, resolverContract };
|
|
@@ -1,227 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Internal resolver error helpers.
|
|
3
|
-
*
|
|
4
|
-
* Keeps validation aggregation and nested-error flattening separate from
|
|
5
|
-
* resolution orchestration.
|
|
6
|
-
*
|
|
7
|
-
* @module dreamcli/core/resolve/errors
|
|
8
|
-
* @internal
|
|
9
|
-
*/
|
|
10
|
-
|
|
11
|
-
import type { ValidationErrorCode } from '#internals/core/errors/index.ts';
|
|
12
|
-
import { ValidationError } from '#internals/core/errors/index.ts';
|
|
13
|
-
|
|
14
|
-
type AggregateIssueSourceKind = 'env' | 'config' | 'stdin' | 'prompt';
|
|
15
|
-
|
|
16
|
-
interface AggregateIssueSummary {
|
|
17
|
-
readonly code: ValidationErrorCode;
|
|
18
|
-
readonly inputKind: 'flag' | 'arg' | 'input';
|
|
19
|
-
readonly name?: string;
|
|
20
|
-
readonly label: string;
|
|
21
|
-
readonly message: string;
|
|
22
|
-
readonly sourceKind?: AggregateIssueSourceKind;
|
|
23
|
-
readonly sourceLabel?: string;
|
|
24
|
-
}
|
|
25
|
-
|
|
26
|
-
function isRecord(value: unknown): value is Record<string, unknown> {
|
|
27
|
-
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
28
|
-
}
|
|
29
|
-
|
|
30
|
-
function readStringProperty(record: object, key: string): string | undefined {
|
|
31
|
-
const value = Reflect.get(record, key);
|
|
32
|
-
return typeof value === 'string' ? value : undefined;
|
|
33
|
-
}
|
|
34
|
-
|
|
35
|
-
function hasValueProperty(record: object, key: string): boolean {
|
|
36
|
-
return Object.hasOwn(record, key);
|
|
37
|
-
}
|
|
38
|
-
|
|
39
|
-
function describeIssueSource(
|
|
40
|
-
details: object,
|
|
41
|
-
): { readonly kind: AggregateIssueSourceKind; readonly label: string } | undefined {
|
|
42
|
-
const explicitSource = readStringProperty(details, 'source');
|
|
43
|
-
if (explicitSource === 'stdin') {
|
|
44
|
-
return { kind: 'stdin', label: 'stdin' };
|
|
45
|
-
}
|
|
46
|
-
|
|
47
|
-
if (explicitSource === 'prompt') {
|
|
48
|
-
return { kind: 'prompt', label: 'prompt' };
|
|
49
|
-
}
|
|
50
|
-
|
|
51
|
-
if (hasValueProperty(details, 'value')) {
|
|
52
|
-
const envVar = readStringProperty(details, 'envVar');
|
|
53
|
-
if (envVar !== undefined) {
|
|
54
|
-
return { kind: 'env', label: `env ${envVar}` };
|
|
55
|
-
}
|
|
56
|
-
|
|
57
|
-
const configPath = readStringProperty(details, 'configPath');
|
|
58
|
-
if (configPath !== undefined) {
|
|
59
|
-
return { kind: 'config', label: `config ${configPath}` };
|
|
60
|
-
}
|
|
61
|
-
}
|
|
62
|
-
|
|
63
|
-
return undefined;
|
|
64
|
-
}
|
|
65
|
-
|
|
66
|
-
function summarizeValidationError(error: ValidationError): AggregateIssueSummary {
|
|
67
|
-
const details = error.details;
|
|
68
|
-
if (!isRecord(details)) {
|
|
69
|
-
return {
|
|
70
|
-
code: error.code,
|
|
71
|
-
inputKind: 'input',
|
|
72
|
-
label: 'input',
|
|
73
|
-
message: error.message,
|
|
74
|
-
};
|
|
75
|
-
}
|
|
76
|
-
|
|
77
|
-
const flag = readStringProperty(details, 'flag');
|
|
78
|
-
if (flag !== undefined) {
|
|
79
|
-
const source = describeIssueSource(details);
|
|
80
|
-
return {
|
|
81
|
-
code: error.code,
|
|
82
|
-
inputKind: 'flag',
|
|
83
|
-
name: flag,
|
|
84
|
-
label: `flag --${flag}`,
|
|
85
|
-
message: error.message,
|
|
86
|
-
...(source !== undefined ? { sourceKind: source.kind, sourceLabel: source.label } : {}),
|
|
87
|
-
};
|
|
88
|
-
}
|
|
89
|
-
|
|
90
|
-
const arg = readStringProperty(details, 'arg');
|
|
91
|
-
if (arg !== undefined) {
|
|
92
|
-
const source = describeIssueSource(details);
|
|
93
|
-
return {
|
|
94
|
-
code: error.code,
|
|
95
|
-
inputKind: 'arg',
|
|
96
|
-
name: arg,
|
|
97
|
-
label: `argument <${arg}>`,
|
|
98
|
-
message: error.message,
|
|
99
|
-
...(source !== undefined ? { sourceKind: source.kind, sourceLabel: source.label } : {}),
|
|
100
|
-
};
|
|
101
|
-
}
|
|
102
|
-
|
|
103
|
-
return {
|
|
104
|
-
code: error.code,
|
|
105
|
-
inputKind: 'input',
|
|
106
|
-
label: 'input',
|
|
107
|
-
message: error.message,
|
|
108
|
-
};
|
|
109
|
-
}
|
|
110
|
-
|
|
111
|
-
function formatAggregateHeadline(issues: readonly AggregateIssueSummary[]): string {
|
|
112
|
-
const flagCount = issues.filter((issue) => issue.inputKind === 'flag').length;
|
|
113
|
-
const argCount = issues.filter((issue) => issue.inputKind === 'arg').length;
|
|
114
|
-
const otherCount = issues.length - flagCount - argCount;
|
|
115
|
-
const counts: string[] = [];
|
|
116
|
-
|
|
117
|
-
if (flagCount > 0) {
|
|
118
|
-
counts.push(`${flagCount} flag${flagCount === 1 ? '' : 's'}`);
|
|
119
|
-
}
|
|
120
|
-
|
|
121
|
-
if (argCount > 0) {
|
|
122
|
-
counts.push(`${argCount} arg${argCount === 1 ? '' : 's'}`);
|
|
123
|
-
}
|
|
124
|
-
|
|
125
|
-
if (otherCount > 0) {
|
|
126
|
-
counts.push(`${otherCount} input${otherCount === 1 ? '' : 's'}`);
|
|
127
|
-
}
|
|
128
|
-
|
|
129
|
-
return counts.length === 0
|
|
130
|
-
? `Multiple validation errors (${issues.length})`
|
|
131
|
-
: `Multiple validation errors (${counts.join(', ')})`;
|
|
132
|
-
}
|
|
133
|
-
|
|
134
|
-
function formatAggregateLine(issue: AggregateIssueSummary): string {
|
|
135
|
-
const source = issue.sourceLabel !== undefined ? ` [${issue.sourceLabel}]` : '';
|
|
136
|
-
return `${issue.label}${source}: ${issue.message}`;
|
|
137
|
-
}
|
|
138
|
-
|
|
139
|
-
/** Type-narrowing guard that asserts a readonly array has at least one element. */
|
|
140
|
-
function isNonEmpty<T>(arr: readonly T[]): arr is readonly [T, ...T[]] {
|
|
141
|
-
return arr.length > 0;
|
|
142
|
-
}
|
|
143
|
-
|
|
144
|
-
function isValidationErrorJson(value: unknown): value is {
|
|
145
|
-
readonly code: ValidationErrorCode;
|
|
146
|
-
readonly message: string;
|
|
147
|
-
readonly exitCode: number;
|
|
148
|
-
readonly suggest?: string;
|
|
149
|
-
readonly details?: Readonly<Record<string, unknown>>;
|
|
150
|
-
} {
|
|
151
|
-
if (value === null || typeof value !== 'object') {
|
|
152
|
-
return false;
|
|
153
|
-
}
|
|
154
|
-
|
|
155
|
-
if (!('code' in value) || !('message' in value) || !('exitCode' in value)) {
|
|
156
|
-
return false;
|
|
157
|
-
}
|
|
158
|
-
|
|
159
|
-
if (typeof value.code !== 'string' || typeof value.message !== 'string') {
|
|
160
|
-
return false;
|
|
161
|
-
}
|
|
162
|
-
|
|
163
|
-
if (typeof value.exitCode !== 'number') {
|
|
164
|
-
return false;
|
|
165
|
-
}
|
|
166
|
-
|
|
167
|
-
if ('suggest' in value && value.suggest !== undefined && typeof value.suggest !== 'string') {
|
|
168
|
-
return false;
|
|
169
|
-
}
|
|
170
|
-
|
|
171
|
-
if (
|
|
172
|
-
'details' in value &&
|
|
173
|
-
value.details !== undefined &&
|
|
174
|
-
(value.details === null || typeof value.details !== 'object')
|
|
175
|
-
) {
|
|
176
|
-
return false;
|
|
177
|
-
}
|
|
178
|
-
|
|
179
|
-
return true;
|
|
180
|
-
}
|
|
181
|
-
|
|
182
|
-
/** Flatten an aggregate validation error's nested `details.errors` into individual errors, or return the original as a singleton. */
|
|
183
|
-
function collectValidationErrors(error: ValidationError): readonly ValidationError[] {
|
|
184
|
-
const nestedErrors = error.details?.errors;
|
|
185
|
-
if (!Array.isArray(nestedErrors)) {
|
|
186
|
-
return [error];
|
|
187
|
-
}
|
|
188
|
-
|
|
189
|
-
const flattened: ValidationError[] = [];
|
|
190
|
-
for (const entry of nestedErrors) {
|
|
191
|
-
if (!isValidationErrorJson(entry)) {
|
|
192
|
-
return [error];
|
|
193
|
-
}
|
|
194
|
-
|
|
195
|
-
flattened.push(
|
|
196
|
-
new ValidationError(entry.message, {
|
|
197
|
-
code: entry.code,
|
|
198
|
-
exitCode: entry.exitCode,
|
|
199
|
-
...(entry.suggest !== undefined ? { suggest: entry.suggest } : {}),
|
|
200
|
-
...(entry.details !== undefined ? { details: entry.details } : {}),
|
|
201
|
-
}),
|
|
202
|
-
);
|
|
203
|
-
}
|
|
204
|
-
|
|
205
|
-
return flattened;
|
|
206
|
-
}
|
|
207
|
-
|
|
208
|
-
/** Throw a single error if one, or an aggregate with per-issue summaries if many. */
|
|
209
|
-
function throwAggregatedErrors(errors: readonly [ValidationError, ...ValidationError[]]): never {
|
|
210
|
-
if (errors.length === 1) {
|
|
211
|
-
throw errors[0];
|
|
212
|
-
}
|
|
213
|
-
|
|
214
|
-
const issues = errors.map(summarizeValidationError);
|
|
215
|
-
const lines = issues.map(formatAggregateLine);
|
|
216
|
-
throw new ValidationError(`${formatAggregateHeadline(issues)}:\n - ${lines.join('\n - ')}`, {
|
|
217
|
-
code: errors[0].code,
|
|
218
|
-
details: {
|
|
219
|
-
errors: errors.map((error) => error.toJSON()),
|
|
220
|
-
count: errors.length,
|
|
221
|
-
issues,
|
|
222
|
-
},
|
|
223
|
-
suggest: 'Fix the listed validation errors and retry',
|
|
224
|
-
});
|
|
225
|
-
}
|
|
226
|
-
|
|
227
|
-
export { collectValidationErrors, isNonEmpty, throwAggregatedErrors };
|
|
@@ -1,269 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Internal flag resolution helpers.
|
|
3
|
-
*
|
|
4
|
-
* @module dreamcli/core/resolve/flags
|
|
5
|
-
* @internal
|
|
6
|
-
*/
|
|
7
|
-
|
|
8
|
-
import { ValidationError } from '#internals/core/errors/index.ts';
|
|
9
|
-
import type { PromptEngine } from '#internals/core/prompt/index.ts';
|
|
10
|
-
import { resolvePromptConfig } from '#internals/core/prompt/index.ts';
|
|
11
|
-
import type { ErasedInteractiveResolver } from '#internals/core/schema/command.ts';
|
|
12
|
-
import type { FlagKind, FlagSchema } from '#internals/core/schema/flag.ts';
|
|
13
|
-
import type { PromptConfig, PromptKind } from '#internals/core/schema/prompt.ts';
|
|
14
|
-
import { coerceValue } from './coerce.ts';
|
|
15
|
-
import { resolveConfigPath } from './config.ts';
|
|
16
|
-
import type { DeprecationWarning } from './contracts.ts';
|
|
17
|
-
import { isNonEmpty, throwAggregatedErrors } from './errors.ts';
|
|
18
|
-
|
|
19
|
-
type PromptResolveResult =
|
|
20
|
-
| { readonly ok: true; readonly value: unknown }
|
|
21
|
-
| { readonly ok: false; readonly error: ValidationError | undefined };
|
|
22
|
-
|
|
23
|
-
/** Walk every declared flag through the resolution chain (cli -> env -> config -> prompt -> default), collecting deprecations and throwing aggregated errors. */
|
|
24
|
-
async function resolveFlags(
|
|
25
|
-
flagSchemas: Readonly<Record<string, FlagSchema>>,
|
|
26
|
-
parsedFlags: Readonly<Record<string, unknown>>,
|
|
27
|
-
env: Readonly<Record<string, string | undefined>>,
|
|
28
|
-
config: Readonly<Record<string, unknown>>,
|
|
29
|
-
prompter: PromptEngine | undefined,
|
|
30
|
-
interactive: ErasedInteractiveResolver | undefined,
|
|
31
|
-
deprecations: DeprecationWarning[],
|
|
32
|
-
): Promise<Readonly<Record<string, unknown>>> {
|
|
33
|
-
const resolved: Record<string, unknown> = {};
|
|
34
|
-
const errors: ValidationError[] = [];
|
|
35
|
-
const hardErrorFlags = new Set<string>();
|
|
36
|
-
|
|
37
|
-
for (const [name, schema] of Object.entries(flagSchemas)) {
|
|
38
|
-
const hasParsedValue = Object.hasOwn(parsedFlags, name);
|
|
39
|
-
const parsedValue = parsedFlags[name];
|
|
40
|
-
|
|
41
|
-
if (hasParsedValue && parsedValue !== undefined) {
|
|
42
|
-
if (schema.deprecated !== undefined) {
|
|
43
|
-
deprecations.push({ kind: 'flag', name, message: schema.deprecated });
|
|
44
|
-
}
|
|
45
|
-
resolved[name] = parsedValue;
|
|
46
|
-
continue;
|
|
47
|
-
}
|
|
48
|
-
|
|
49
|
-
if (schema.envVar !== undefined) {
|
|
50
|
-
const envValue = env[schema.envVar];
|
|
51
|
-
if (envValue !== undefined) {
|
|
52
|
-
const coerced = coerceValue(name, { kind: 'env', envVar: schema.envVar }, envValue, schema);
|
|
53
|
-
if (coerced.ok) {
|
|
54
|
-
if (schema.deprecated !== undefined) {
|
|
55
|
-
deprecations.push({ kind: 'flag', name, message: schema.deprecated });
|
|
56
|
-
}
|
|
57
|
-
resolved[name] = coerced.value;
|
|
58
|
-
continue;
|
|
59
|
-
}
|
|
60
|
-
errors.push(coerced.error);
|
|
61
|
-
hardErrorFlags.add(name);
|
|
62
|
-
continue;
|
|
63
|
-
}
|
|
64
|
-
}
|
|
65
|
-
|
|
66
|
-
if (schema.configPath !== undefined) {
|
|
67
|
-
const configValue = resolveConfigPath(config, schema.configPath);
|
|
68
|
-
if (configValue !== undefined) {
|
|
69
|
-
const coerced = coerceValue(
|
|
70
|
-
name,
|
|
71
|
-
{ kind: 'config', configPath: schema.configPath },
|
|
72
|
-
configValue,
|
|
73
|
-
schema,
|
|
74
|
-
);
|
|
75
|
-
if (coerced.ok) {
|
|
76
|
-
if (schema.deprecated !== undefined) {
|
|
77
|
-
deprecations.push({ kind: 'flag', name, message: schema.deprecated });
|
|
78
|
-
}
|
|
79
|
-
resolved[name] = coerced.value;
|
|
80
|
-
continue;
|
|
81
|
-
}
|
|
82
|
-
errors.push(coerced.error);
|
|
83
|
-
hardErrorFlags.add(name);
|
|
84
|
-
}
|
|
85
|
-
}
|
|
86
|
-
}
|
|
87
|
-
|
|
88
|
-
const interactiveConfigs =
|
|
89
|
-
interactive !== undefined ? interactive({ flags: resolved }) : undefined;
|
|
90
|
-
|
|
91
|
-
for (const [name, schema] of Object.entries(flagSchemas)) {
|
|
92
|
-
if (Object.hasOwn(resolved, name) || hardErrorFlags.has(name)) {
|
|
93
|
-
continue;
|
|
94
|
-
}
|
|
95
|
-
|
|
96
|
-
const interactiveConfig = interactiveConfigs?.[name];
|
|
97
|
-
|
|
98
|
-
let effectivePromptConfig: PromptConfig | undefined;
|
|
99
|
-
// `interactiveConfig === false` explicitly disables prompts for this flag.
|
|
100
|
-
// Other falsy values mean "no override", so we fall back to `schema.prompt`.
|
|
101
|
-
if (
|
|
102
|
-
interactiveConfig !== undefined &&
|
|
103
|
-
interactiveConfig !== null &&
|
|
104
|
-
interactiveConfig !== false &&
|
|
105
|
-
interactiveConfig !== 0 &&
|
|
106
|
-
interactiveConfig !== ''
|
|
107
|
-
) {
|
|
108
|
-
effectivePromptConfig = interactiveConfig;
|
|
109
|
-
} else if (interactiveConfig === false) {
|
|
110
|
-
effectivePromptConfig = undefined;
|
|
111
|
-
} else {
|
|
112
|
-
effectivePromptConfig = schema.prompt;
|
|
113
|
-
}
|
|
114
|
-
|
|
115
|
-
if (effectivePromptConfig !== undefined && prompter !== undefined) {
|
|
116
|
-
const promptResult = await resolvePromptValueWithConfig(
|
|
117
|
-
name,
|
|
118
|
-
schema,
|
|
119
|
-
effectivePromptConfig,
|
|
120
|
-
prompter,
|
|
121
|
-
);
|
|
122
|
-
if (promptResult.ok) {
|
|
123
|
-
if (schema.deprecated !== undefined) {
|
|
124
|
-
deprecations.push({ kind: 'flag', name, message: schema.deprecated });
|
|
125
|
-
}
|
|
126
|
-
resolved[name] = promptResult.value;
|
|
127
|
-
continue;
|
|
128
|
-
}
|
|
129
|
-
if (promptResult.error !== undefined) {
|
|
130
|
-
errors.push(promptResult.error);
|
|
131
|
-
continue;
|
|
132
|
-
}
|
|
133
|
-
}
|
|
134
|
-
|
|
135
|
-
if (schema.defaultValue !== undefined) {
|
|
136
|
-
resolved[name] = schema.defaultValue;
|
|
137
|
-
continue;
|
|
138
|
-
}
|
|
139
|
-
|
|
140
|
-
if (schema.kind === 'array' && schema.presence !== 'required') {
|
|
141
|
-
resolved[name] = [];
|
|
142
|
-
continue;
|
|
143
|
-
}
|
|
144
|
-
|
|
145
|
-
if (schema.presence === 'required') {
|
|
146
|
-
const details: Record<string, unknown> = { flag: name, kind: schema.kind };
|
|
147
|
-
if (schema.envVar !== undefined) details.envVar = schema.envVar;
|
|
148
|
-
if (schema.configPath !== undefined) details.configPath = schema.configPath;
|
|
149
|
-
errors.push(
|
|
150
|
-
new ValidationError(`Missing required flag --${name}`, {
|
|
151
|
-
code: 'REQUIRED_FLAG',
|
|
152
|
-
details,
|
|
153
|
-
suggest: buildRequiredFlagSuggest(name, schema),
|
|
154
|
-
}),
|
|
155
|
-
);
|
|
156
|
-
continue;
|
|
157
|
-
}
|
|
158
|
-
|
|
159
|
-
resolved[name] = undefined;
|
|
160
|
-
}
|
|
161
|
-
|
|
162
|
-
if (isNonEmpty(errors)) {
|
|
163
|
-
throwAggregatedErrors(errors);
|
|
164
|
-
}
|
|
165
|
-
|
|
166
|
-
return resolved;
|
|
167
|
-
}
|
|
168
|
-
|
|
169
|
-
/** Maps each flag kind to the prompt kinds that produce compatible values. */
|
|
170
|
-
const COMPATIBLE_PROMPT_KINDS: Record<FlagKind, readonly PromptKind[]> = {
|
|
171
|
-
boolean: ['confirm'],
|
|
172
|
-
string: ['input', 'select'],
|
|
173
|
-
number: ['input'],
|
|
174
|
-
enum: ['select', 'input'],
|
|
175
|
-
array: ['multiselect'],
|
|
176
|
-
custom: ['input', 'select', 'confirm', 'multiselect'],
|
|
177
|
-
};
|
|
178
|
-
|
|
179
|
-
/**
|
|
180
|
-
* Check whether a prompt kind is compatible with the flag's declared kind.
|
|
181
|
-
*
|
|
182
|
-
* @returns `undefined` when compatible, or a {@link ValidationError} with
|
|
183
|
-
* code `'CONSTRAINT_VIOLATED'` and an actionable `suggest` message when not.
|
|
184
|
-
* @internal
|
|
185
|
-
*/
|
|
186
|
-
function validatePromptFlagCompatibility(
|
|
187
|
-
flagName: string,
|
|
188
|
-
flagKind: FlagKind,
|
|
189
|
-
promptKind: PromptKind,
|
|
190
|
-
): ValidationError | undefined {
|
|
191
|
-
const allowed = COMPATIBLE_PROMPT_KINDS[flagKind];
|
|
192
|
-
if (allowed.includes(promptKind)) return undefined;
|
|
193
|
-
|
|
194
|
-
return new ValidationError(
|
|
195
|
-
`Prompt kind '${promptKind}' is not compatible with ${flagKind} flag --${flagName}. Use '${allowed[0]}' instead`,
|
|
196
|
-
{
|
|
197
|
-
code: 'CONSTRAINT_VIOLATED',
|
|
198
|
-
details: { flag: flagName, flagKind, promptKind, allowed },
|
|
199
|
-
suggest: `Change the prompt to { kind: '${allowed[0]}' } for --${flagName}`,
|
|
200
|
-
},
|
|
201
|
-
);
|
|
202
|
-
}
|
|
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(
|
|
213
|
-
flagName: string,
|
|
214
|
-
schema: FlagSchema,
|
|
215
|
-
promptConfig: PromptConfig,
|
|
216
|
-
prompter: PromptEngine,
|
|
217
|
-
): Promise<PromptResolveResult> {
|
|
218
|
-
const mismatch = validatePromptFlagCompatibility(flagName, schema.kind, promptConfig.kind);
|
|
219
|
-
if (mismatch !== undefined) {
|
|
220
|
-
return { ok: false, error: mismatch };
|
|
221
|
-
}
|
|
222
|
-
|
|
223
|
-
const resolvedConfig = resolvePromptConfig(promptConfig, schema.enumValues);
|
|
224
|
-
const result = await prompter.promptOne(resolvedConfig);
|
|
225
|
-
|
|
226
|
-
if (!result.answered) {
|
|
227
|
-
return { ok: false, error: undefined };
|
|
228
|
-
}
|
|
229
|
-
|
|
230
|
-
// An empty/blank `input` answer with no prompt-level default is not a real
|
|
231
|
-
// answer — fall through (ok: false) so resolution reaches the flag's
|
|
232
|
-
// `.default()`. When a prompt-level default exists, the prompt engine has
|
|
233
|
-
// already applied it (so the value is the default, not blank), giving it
|
|
234
|
-
// precedence over the flag default.
|
|
235
|
-
if (
|
|
236
|
-
promptConfig.kind === 'input' &&
|
|
237
|
-
promptConfig.default === undefined &&
|
|
238
|
-
typeof result.value === 'string' &&
|
|
239
|
-
result.value.trim() === ''
|
|
240
|
-
) {
|
|
241
|
-
return { ok: false, error: undefined };
|
|
242
|
-
}
|
|
243
|
-
|
|
244
|
-
return coerceValue(flagName, { kind: 'prompt' }, result.value, schema);
|
|
245
|
-
}
|
|
246
|
-
|
|
247
|
-
/** Build a human-readable suggestion listing all available sources for a required flag. @internal */
|
|
248
|
-
function buildRequiredFlagSuggest(name: string, schema: FlagSchema): string {
|
|
249
|
-
const sources: string[] = [];
|
|
250
|
-
sources.push(`Provide --${name}${schema.kind !== 'boolean' ? ' <value>' : ''}`);
|
|
251
|
-
|
|
252
|
-
if (schema.envVar !== undefined) {
|
|
253
|
-
sources.push(`set ${schema.envVar}`);
|
|
254
|
-
}
|
|
255
|
-
|
|
256
|
-
if (schema.configPath !== undefined) {
|
|
257
|
-
sources.push(`add ${schema.configPath} to config`);
|
|
258
|
-
}
|
|
259
|
-
|
|
260
|
-
if (sources.length <= 1) {
|
|
261
|
-
return sources.join('');
|
|
262
|
-
}
|
|
263
|
-
|
|
264
|
-
const rest = sources.slice(0, -1);
|
|
265
|
-
const last = sources.slice(-1).join('');
|
|
266
|
-
return sources.length === 2 ? `${rest.join('')} or ${last}` : `${rest.join(', ')}, or ${last}`;
|
|
267
|
-
}
|
|
268
|
-
|
|
269
|
-
export { COMPATIBLE_PROMPT_KINDS, resolveFlags };
|