@kjanat/dreamcli 3.0.1 → 4.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 +962 -1
- package/README.md +7 -3
- package/dist/core/cli/builtins.d.mts +47 -0
- package/dist/core/cli/builtins.mjs +135 -0
- package/dist/core/cli/compiled.d.mts +29 -0
- package/dist/core/cli/compiled.mjs +76 -0
- package/dist/core/cli/dispatch.d.mts +9 -85
- package/dist/core/cli/help-links.d.mts +2 -14
- package/dist/core/cli/index.d.mts +282 -101
- package/dist/core/cli/index.mjs +497 -264
- package/dist/core/cli/planner.d.mts +13 -86
- package/dist/core/cli/planner.mjs +47 -30
- package/dist/core/cli/plugin.d.mts +1 -1
- package/dist/core/cli/propagate.mjs +1 -1
- package/dist/core/cli/reserved-flags.d.mts +1 -0
- package/dist/core/cli/reserved-flags.mjs +158 -0
- package/dist/core/cli/root-help.d.mts +1 -47
- package/dist/core/cli/root-help.mjs +37 -47
- package/dist/core/cli/root-output-flags.d.mts +1 -0
- package/dist/core/cli/root-output-flags.mjs +169 -0
- package/dist/core/cli/root-surface.d.mts +1 -68
- package/dist/core/cli/root-surface.mjs +2 -2
- package/dist/core/cli/runtime-preflight.d.mts +1 -199
- package/dist/core/cli/runtime-preflight.mjs +67 -17
- package/dist/core/completion/index.d.mts +2 -2
- package/dist/core/completion/shells/bash.d.mts +0 -1
- package/dist/core/completion/shells/bash.mjs +2 -1
- package/dist/core/completion/shells/fish.d.mts +0 -1
- package/dist/core/completion/shells/fish.mjs +2 -1
- package/dist/core/completion/shells/powershell.d.mts +0 -1
- package/dist/core/completion/shells/powershell.mjs +2 -1
- package/dist/core/completion/shells/shared.d.mts +3 -114
- package/dist/core/completion/shells/shared.mjs +9 -39
- package/dist/core/completion/shells/zsh.d.mts +0 -1
- package/dist/core/completion/shells/zsh.mjs +2 -1
- package/dist/core/config/index.d.mts +3 -3
- package/dist/core/config/index.mjs +2 -2
- package/dist/core/config/package-json.d.mts +2 -33
- package/dist/core/config/package-json.mjs +1 -34
- package/dist/core/errors/index.d.mts +7 -7
- package/dist/core/execution/index.d.mts +1 -48
- package/dist/core/execution/index.mjs +42 -27
- package/dist/core/help/ansi.d.mts +0 -11
- package/dist/core/help/index.d.mts +3 -35
- package/dist/core/help/index.mjs +29 -6
- package/dist/core/help/theme.d.mts +1 -21
- package/dist/core/json-schema/index.d.mts +279 -10
- package/dist/core/json-schema/index.mjs +482 -237
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +79 -7
- package/dist/core/json-schema/meta-descriptions.generated.mjs +40 -6
- package/dist/core/output/activity.d.mts +1 -193
- package/dist/core/output/activity.mjs +1 -1
- package/dist/core/output/bind.d.mts +1 -37
- package/dist/core/output/contracts.d.mts +7 -13
- package/dist/core/output/contracts.mjs +1 -1
- package/dist/core/output/display-value.d.mts +1 -19
- package/dist/core/output/index.d.mts +5 -187
- package/dist/core/output/index.mjs +44 -9
- package/dist/core/output/renderers.d.mts +1 -45
- package/dist/core/output/writer.d.mts +0 -1
- package/dist/core/parse/index.d.mts +27 -5
- package/dist/core/parse/index.mjs +350 -227
- package/dist/core/parse/occurrences.d.mts +89 -0
- package/dist/core/parse/occurrences.mjs +114 -0
- package/dist/core/prompt/index.d.mts +3 -3
- package/dist/core/read-flags/index.d.mts +150 -0
- package/dist/core/read-flags/index.mjs +217 -0
- package/dist/core/resolve/args.d.mts +35 -4
- package/dist/core/resolve/args.mjs +132 -55
- package/dist/core/resolve/coerce.d.mts +66 -9
- package/dist/core/resolve/coerce.mjs +834 -270
- package/dist/core/resolve/config.d.mts +1 -10
- package/dist/core/resolve/contracts.d.mts +67 -44
- package/dist/core/resolve/errors.mjs +29 -21
- package/dist/core/resolve/flags.d.mts +36 -9
- package/dist/core/resolve/flags.mjs +129 -151
- package/dist/core/resolve/index.d.mts +8 -6
- package/dist/core/resolve/index.mjs +51 -18
- package/dist/core/resolve/path-checks.d.mts +47 -0
- package/dist/core/resolve/path-checks.mjs +102 -0
- package/dist/core/resolve/redaction.d.mts +12 -0
- package/dist/core/resolve/redaction.mjs +14 -0
- package/dist/core/resolve/stages.d.mts +85 -0
- package/dist/core/resolve/stages.mjs +170 -0
- package/dist/core/resolve/standard.d.mts +1 -24
- package/dist/core/resolve/standard.mjs +141 -43
- package/dist/core/schema/activity.d.mts +16 -16
- package/dist/core/schema/arg.d.mts +849 -71
- package/dist/core/schema/arg.mjs +727 -54
- package/dist/core/schema/brand.d.mts +17 -0
- package/dist/core/schema/cardinality.d.mts +301 -0
- package/dist/core/schema/cardinality.mjs +514 -0
- package/dist/core/schema/command.d.mts +173 -119
- package/dist/core/schema/command.mjs +305 -42
- package/dist/core/schema/flag.d.mts +515 -173
- package/dist/core/schema/flag.mjs +576 -78
- package/dist/core/schema/index.d.mts +11 -8
- package/dist/core/schema/index.mjs +10 -0
- package/dist/core/schema/middleware.d.mts +15 -12
- package/dist/core/schema/number-constraints.d.mts +5 -5
- package/dist/core/schema/prompt.d.mts +4 -4
- package/dist/core/schema/provenance.d.mts +99 -0
- package/dist/core/schema/provenance.mjs +28 -0
- package/dist/core/schema/run.d.mts +21 -60
- package/dist/core/schema/source.d.mts +179 -0
- package/dist/core/schema/source.mjs +206 -0
- package/dist/core/schema/standard.d.mts +12 -19
- package/dist/core/schema/stdin.d.mts +87 -0
- package/dist/core/schema/stdin.mjs +91 -0
- package/dist/core/schema/string-constraints.d.mts +16 -5
- package/dist/core/schema/string-constraints.mjs +18 -1
- package/dist/core/schema/value-parsers.d.mts +81 -9
- package/dist/core/schema/value-parsers.mjs +19 -1
- package/dist/core/schema/value.d.mts +242 -0
- package/dist/core/schema/value.mjs +573 -0
- package/dist/core/testkit/index.d.mts +30 -3
- package/dist/core/testkit/index.mjs +40 -26
- package/dist/index.d.mts +21 -16
- package/dist/index.mjs +10 -6
- package/dist/runtime/adapter.d.mts +3 -3
- package/dist/runtime/deno.d.mts +3 -3
- package/dist/runtime/detect.d.mts +2 -2
- package/dist/runtime/node.d.mts +3 -3
- package/dist/runtime/paths.d.mts +1 -31
- package/dist/runtime.d.mts +4 -4
- package/dist/strings.d.mts +1 -16
- package/dist/testkit.d.mts +2 -2
- package/dist/testkit.mjs +1 -1
- package/dist/version.d.mts +0 -13
- package/dist/version.mjs +2 -2
- package/dreamcli.schema.json +368 -78
- package/examples/interactive.ts +6 -5
- package/package.json +12 -11
- package/skills/cli-creation/SKILL.md +72 -16
- package/skills/cli-creation/references/pattern-cookbook.md +169 -11
- package/dist/core/resolve/property.d.mts +0 -51
- package/dist/core/resolve/property.mjs +0 -53
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
import { STDIN_SENTINEL } from "../schema/source.mjs";
|
|
2
|
+
//#region src/core/parse/occurrences.d.ts
|
|
3
|
+
/**
|
|
4
|
+
* One occurrence of an input on the command line.
|
|
5
|
+
*
|
|
6
|
+
* - `'value'`: one decoded value, or one element of a collection
|
|
7
|
+
* - `'entry'`: one decoded `KEY=VALUE` pair
|
|
8
|
+
* - `'stdin'`: the position a `-` selector holds
|
|
9
|
+
* - `'negated'`: a `--no-x` spelling
|
|
10
|
+
* - `'increment'`: one bare occurrence of a count flag
|
|
11
|
+
* - `'aggregated'`: a value a caller aggregated before the resolver saw it
|
|
12
|
+
*/
|
|
13
|
+
type Occurrence = {
|
|
14
|
+
readonly kind: "value";
|
|
15
|
+
readonly value: unknown;
|
|
16
|
+
} | {
|
|
17
|
+
readonly kind: "entry";
|
|
18
|
+
readonly key: string;
|
|
19
|
+
readonly value: unknown;
|
|
20
|
+
} | {
|
|
21
|
+
readonly kind: "stdin";
|
|
22
|
+
} | {
|
|
23
|
+
readonly kind: "negated";
|
|
24
|
+
} | {
|
|
25
|
+
readonly kind: "increment";
|
|
26
|
+
} | {
|
|
27
|
+
readonly kind: "aggregated";
|
|
28
|
+
readonly value: unknown;
|
|
29
|
+
};
|
|
30
|
+
/** The sentinel occurrence, shared by every `-` position. */
|
|
31
|
+
declare const STDIN_OCCURRENCE: Occurrence;
|
|
32
|
+
/** The negated occurrence, shared by every `--no-x` spelling. */
|
|
33
|
+
declare const NEGATED_OCCURRENCE: Occurrence;
|
|
34
|
+
/** One bare occurrence of a count flag. */
|
|
35
|
+
declare const INCREMENT_OCCURRENCE: Occurrence;
|
|
36
|
+
/**
|
|
37
|
+
* The value one occurrence stands for in a parse result.
|
|
38
|
+
*
|
|
39
|
+
* @param occurrence - The occurrence to read.
|
|
40
|
+
* @returns What a parse result carries for it.
|
|
41
|
+
*/
|
|
42
|
+
declare function occurrenceValue(occurrence: Occurrence): unknown;
|
|
43
|
+
/**
|
|
44
|
+
* Project one input's occurrences onto the value a parse result carries.
|
|
45
|
+
*
|
|
46
|
+
* A scalar keeps its last occurrence, a count folds its increments and its
|
|
47
|
+
* explicit values, and a collection keeps every occurrence in order for the
|
|
48
|
+
* resolver to aggregate.
|
|
49
|
+
*
|
|
50
|
+
* @param cardinality - How the input's values combine.
|
|
51
|
+
* @param occurrences - Every occurrence of the input, in order.
|
|
52
|
+
* @returns The parse result's value for it.
|
|
53
|
+
*/
|
|
54
|
+
declare function projectOccurrences(cardinality: Cardinality, occurrences: readonly Occurrence[]): unknown;
|
|
55
|
+
/**
|
|
56
|
+
* Read what a parse result carries for a collection back as occurrences.
|
|
57
|
+
*
|
|
58
|
+
* A value the parser did not leave as a list is an aggregate a caller built by
|
|
59
|
+
* hand, so it stays one opaque occurrence and reaches the resolved value
|
|
60
|
+
* untouched.
|
|
61
|
+
*
|
|
62
|
+
* @param cardinality - The `many` or `entries` axis being filled.
|
|
63
|
+
* @param value - What the parse result carries.
|
|
64
|
+
* @param readsOnDash - Whether the input's stdin binding reacts to `-`.
|
|
65
|
+
* @returns The occurrences behind that value.
|
|
66
|
+
*/
|
|
67
|
+
declare function liftOccurrences(cardinality: Extract<Cardinality, {
|
|
68
|
+
kind: "many";
|
|
69
|
+
} | {
|
|
70
|
+
kind: "entries";
|
|
71
|
+
}>, value: unknown, readsOnDash: boolean): readonly Occurrence[];
|
|
72
|
+
/**
|
|
73
|
+
* The aggregate a caller supplied ready-made.
|
|
74
|
+
*
|
|
75
|
+
* @param occurrences - One input's occurrences.
|
|
76
|
+
* @returns The aggregate, or `undefined` when the occurrences are the parser's.
|
|
77
|
+
*/
|
|
78
|
+
declare function readAggregated(occurrences: readonly Occurrence[]): {
|
|
79
|
+
readonly value: unknown;
|
|
80
|
+
} | undefined;
|
|
81
|
+
/**
|
|
82
|
+
* The pairs an `entries` collection folds, in occurrence order.
|
|
83
|
+
*
|
|
84
|
+
* @param occurrences - The occurrences left after splicing.
|
|
85
|
+
* @returns Every pair among them.
|
|
86
|
+
*/
|
|
87
|
+
declare function entryPairsOf(occurrences: readonly Occurrence[]): readonly (readonly [string, unknown])[];
|
|
88
|
+
//#endregion
|
|
89
|
+
export { INCREMENT_OCCURRENCE, NEGATED_OCCURRENCE, type Occurrence, STDIN_OCCURRENCE, STDIN_SENTINEL, entryPairsOf, liftOccurrences, occurrenceValue, projectOccurrences, readAggregated };
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
import "../schema/source.mjs";
|
|
2
|
+
//#region src/core/parse/occurrences.ts
|
|
3
|
+
/** The sentinel occurrence, shared by every `-` position. */
|
|
4
|
+
const STDIN_OCCURRENCE = { kind: "stdin" };
|
|
5
|
+
/** The negated occurrence, shared by every `--no-x` spelling. */
|
|
6
|
+
const NEGATED_OCCURRENCE = { kind: "negated" };
|
|
7
|
+
/** One bare occurrence of a count flag. */
|
|
8
|
+
const INCREMENT_OCCURRENCE = { kind: "increment" };
|
|
9
|
+
/**
|
|
10
|
+
* The value one occurrence stands for in a parse result.
|
|
11
|
+
*
|
|
12
|
+
* @param occurrence - The occurrence to read.
|
|
13
|
+
* @returns What a parse result carries for it.
|
|
14
|
+
*/
|
|
15
|
+
function occurrenceValue(occurrence) {
|
|
16
|
+
switch (occurrence.kind) {
|
|
17
|
+
case "value": return occurrence.value;
|
|
18
|
+
case "entry": return [occurrence.key, occurrence.value];
|
|
19
|
+
case "stdin": return "-";
|
|
20
|
+
case "negated": return false;
|
|
21
|
+
case "increment": return 1;
|
|
22
|
+
case "aggregated": return occurrence.value;
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Project one input's occurrences onto the value a parse result carries.
|
|
27
|
+
*
|
|
28
|
+
* A scalar keeps its last occurrence, a count folds its increments and its
|
|
29
|
+
* explicit values, and a collection keeps every occurrence in order for the
|
|
30
|
+
* resolver to aggregate.
|
|
31
|
+
*
|
|
32
|
+
* @param cardinality - How the input's values combine.
|
|
33
|
+
* @param occurrences - Every occurrence of the input, in order.
|
|
34
|
+
* @returns The parse result's value for it.
|
|
35
|
+
*/
|
|
36
|
+
function projectOccurrences(cardinality, occurrences) {
|
|
37
|
+
if (cardinality.kind === "count") return projectCount(occurrences);
|
|
38
|
+
if (cardinality.kind === "one") {
|
|
39
|
+
const last = occurrences[occurrences.length - 1];
|
|
40
|
+
return last === void 0 ? void 0 : occurrenceValue(last);
|
|
41
|
+
}
|
|
42
|
+
return occurrences.map(occurrenceValue);
|
|
43
|
+
}
|
|
44
|
+
/** Fold a count flag's increments and explicit values in occurrence order. */
|
|
45
|
+
function projectCount(occurrences) {
|
|
46
|
+
let count;
|
|
47
|
+
for (const occurrence of occurrences) count = occurrence.kind === "increment" ? (typeof count === "number" ? count : 0) + 1 : occurrenceValue(occurrence);
|
|
48
|
+
return count;
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Read what a parse result carries for a collection back as occurrences.
|
|
52
|
+
*
|
|
53
|
+
* A value the parser did not leave as a list is an aggregate a caller built by
|
|
54
|
+
* hand, so it stays one opaque occurrence and reaches the resolved value
|
|
55
|
+
* untouched.
|
|
56
|
+
*
|
|
57
|
+
* @param cardinality - The `many` or `entries` axis being filled.
|
|
58
|
+
* @param value - What the parse result carries.
|
|
59
|
+
* @param readsOnDash - Whether the input's stdin binding reacts to `-`.
|
|
60
|
+
* @returns The occurrences behind that value.
|
|
61
|
+
*/
|
|
62
|
+
function liftOccurrences(cardinality, value, readsOnDash) {
|
|
63
|
+
if (!Array.isArray(value)) return [{
|
|
64
|
+
kind: "aggregated",
|
|
65
|
+
value
|
|
66
|
+
}];
|
|
67
|
+
return value.map((element) => liftElement(cardinality, element, readsOnDash));
|
|
68
|
+
}
|
|
69
|
+
/** Read one element of a parse result's collection as its occurrence. */
|
|
70
|
+
function liftElement(cardinality, element, readsOnDash) {
|
|
71
|
+
if (readsOnDash && element === "-") return STDIN_OCCURRENCE;
|
|
72
|
+
if (cardinality.kind === "entries") {
|
|
73
|
+
const pair = entryPairOf(element);
|
|
74
|
+
if (pair !== void 0) return {
|
|
75
|
+
kind: "entry",
|
|
76
|
+
key: pair[0],
|
|
77
|
+
value: pair[1]
|
|
78
|
+
};
|
|
79
|
+
}
|
|
80
|
+
return {
|
|
81
|
+
kind: "value",
|
|
82
|
+
value: element
|
|
83
|
+
};
|
|
84
|
+
}
|
|
85
|
+
/** Read one element as the `[key, value]` pair an entry occurrence carries. */
|
|
86
|
+
function entryPairOf(element) {
|
|
87
|
+
if (!Array.isArray(element) || element.length !== 2) return void 0;
|
|
88
|
+
const key = element[0];
|
|
89
|
+
const value = element[1];
|
|
90
|
+
return typeof key === "string" ? [key, value] : void 0;
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* The aggregate a caller supplied ready-made.
|
|
94
|
+
*
|
|
95
|
+
* @param occurrences - One input's occurrences.
|
|
96
|
+
* @returns The aggregate, or `undefined` when the occurrences are the parser's.
|
|
97
|
+
*/
|
|
98
|
+
function readAggregated(occurrences) {
|
|
99
|
+
const only = occurrences.length === 1 ? occurrences[0] : void 0;
|
|
100
|
+
return only?.kind === "aggregated" ? { value: only.value } : void 0;
|
|
101
|
+
}
|
|
102
|
+
/**
|
|
103
|
+
* The pairs an `entries` collection folds, in occurrence order.
|
|
104
|
+
*
|
|
105
|
+
* @param occurrences - The occurrences left after splicing.
|
|
106
|
+
* @returns Every pair among them.
|
|
107
|
+
*/
|
|
108
|
+
function entryPairsOf(occurrences) {
|
|
109
|
+
const pairs = [];
|
|
110
|
+
for (const occurrence of occurrences) if (occurrence.kind === "entry") pairs.push([occurrence.key, occurrence.value]);
|
|
111
|
+
return pairs;
|
|
112
|
+
}
|
|
113
|
+
//#endregion
|
|
114
|
+
export { INCREMENT_OCCURRENCE, NEGATED_OCCURRENCE, STDIN_OCCURRENCE, entryPairsOf, liftOccurrences, occurrenceValue, projectOccurrences, readAggregated };
|
|
@@ -10,7 +10,7 @@ import "../output/index.mjs";
|
|
|
10
10
|
*/
|
|
11
11
|
interface ResolvedSelectPromptConfig {
|
|
12
12
|
/** Discriminant — single-choice selection prompt. */
|
|
13
|
-
readonly kind:
|
|
13
|
+
readonly kind: "select";
|
|
14
14
|
/** User-facing question text. */
|
|
15
15
|
readonly message: string;
|
|
16
16
|
/** Non-empty list of selectable options (populated from flag enum values when omitted). */
|
|
@@ -24,7 +24,7 @@ interface ResolvedSelectPromptConfig {
|
|
|
24
24
|
*/
|
|
25
25
|
interface ResolvedMultiselectPromptConfig {
|
|
26
26
|
/** Discriminant — multiple-choice selection prompt. */
|
|
27
|
-
readonly kind:
|
|
27
|
+
readonly kind: "multiselect";
|
|
28
28
|
/** User-facing question text. */
|
|
29
29
|
readonly message: string;
|
|
30
30
|
/** Non-empty list of selectable options (populated from flag enum values when omitted). */
|
|
@@ -132,7 +132,7 @@ interface TestPrompterOptions {
|
|
|
132
132
|
* - `'cancel'` — returns `{ answered: false }`, simulating the
|
|
133
133
|
* user cancelling all subsequent prompts.
|
|
134
134
|
*/
|
|
135
|
-
readonly onExhausted?:
|
|
135
|
+
readonly onExhausted?: "throw" | "cancel";
|
|
136
136
|
}
|
|
137
137
|
/**
|
|
138
138
|
* Create a prompt engine that returns pre-configured answers.
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
import { FlagBuilder, FlagConfig, InferFlags } from "../schema/flag.mjs";
|
|
2
|
+
import { SourcesOf } from "../schema/provenance.mjs";
|
|
3
|
+
import { ParseOptions } from "../parse/index.mjs";
|
|
4
|
+
import { DeprecationWarning, ResolveOptions } from "../resolve/contracts.mjs";
|
|
5
|
+
import "../resolve/index.mjs";
|
|
6
|
+
import { RuntimeAdapter } from "../../runtime/adapter.mjs";
|
|
7
|
+
//#region src/core/read-flags/index.d.ts
|
|
8
|
+
/**
|
|
9
|
+
* A record of flag definitions keyed by canonical flag name.
|
|
10
|
+
*
|
|
11
|
+
* The object key is the `--name` spelling and the key on the resolved record.
|
|
12
|
+
*/
|
|
13
|
+
type FlagMap = Readonly<Record<string, FlagBuilder<FlagConfig>>>;
|
|
14
|
+
/**
|
|
15
|
+
* External state and behavior toggles accepted by {@linkcode readFlags}.
|
|
16
|
+
*
|
|
17
|
+
* Extends {@linkcode ResolveOptions}, so `env`, `config`, `prompter`, `stat`,
|
|
18
|
+
* and `mkdir` carry the meaning they have during command resolution.
|
|
19
|
+
*/
|
|
20
|
+
interface ReadFlagsOptions<F extends FlagMap = FlagMap> extends ResolveOptions {
|
|
21
|
+
/**
|
|
22
|
+
* User arguments only, without the binary and script entries.
|
|
23
|
+
* @defaultValue the runtime adapter's argv past its binary and script entries
|
|
24
|
+
*/
|
|
25
|
+
readonly argv?: readonly string[];
|
|
26
|
+
/**
|
|
27
|
+
* Runtime source for argv, environment, and filesystem primitives.
|
|
28
|
+
* @defaultValue {@linkcode createAdapter | createAdapter()}, built on the
|
|
29
|
+
* first fact the caller left out
|
|
30
|
+
*/
|
|
31
|
+
readonly adapter?: RuntimeAdapter;
|
|
32
|
+
/**
|
|
33
|
+
* Parser behavior such as kebab/camel case parity.
|
|
34
|
+
* @defaultValue `undefined`, which keeps the parser defaults
|
|
35
|
+
*/
|
|
36
|
+
readonly parse?: ParseOptions;
|
|
37
|
+
/**
|
|
38
|
+
* Reject argv content the definitions do not declare.
|
|
39
|
+
*
|
|
40
|
+
* `false` drops undeclared input from argv before parsing: unknown long
|
|
41
|
+
* flags together with their inline `=value`, unknown characters inside a
|
|
42
|
+
* short group, positional arguments, and the `--` separator, which can only
|
|
43
|
+
* introduce positionals here. A value token of a declared flag is kept by
|
|
44
|
+
* walking the same consumption rules the parser applies. Misuse of a
|
|
45
|
+
* declared flag still fails: a missing value, a bad coercion, or a violated
|
|
46
|
+
* duplicate policy throws in either mode.
|
|
47
|
+
* @defaultValue `true`
|
|
48
|
+
*/
|
|
49
|
+
readonly strict?: boolean;
|
|
50
|
+
/**
|
|
51
|
+
* The built-in `--help`/`-h` handling.
|
|
52
|
+
*
|
|
53
|
+
* While `'on'`, a pre-separator `--help` or `-h` prints generated help for
|
|
54
|
+
* the definitions to the adapter's stdout and exits the process with
|
|
55
|
+
* code 0. The built-in yields automatically when any definition claims the
|
|
56
|
+
* `help` or `h` spelling through its name, an alias, a negated form, or a
|
|
57
|
+
* case-parity counterpart; those spellings then parse as the definition's
|
|
58
|
+
* own. `'off'` removes the built-in, and the spellings parse like any other
|
|
59
|
+
* token.
|
|
60
|
+
* @defaultValue `'on'`
|
|
61
|
+
*/
|
|
62
|
+
readonly help?: "on" | "off";
|
|
63
|
+
/**
|
|
64
|
+
* Receiver for notices produced by `.deprecated()` flags.
|
|
65
|
+
* @defaultValue `undefined`, which drops the notices
|
|
66
|
+
*/
|
|
67
|
+
readonly onDeprecation?: (warning: DeprecationWarning) => void;
|
|
68
|
+
/**
|
|
69
|
+
* Receiver for the provenance of the resolved values, keyed by flag name.
|
|
70
|
+
*
|
|
71
|
+
* Called once with the whole record, before {@linkcode readFlags} returns the
|
|
72
|
+
* values. A flag that resolved no value has no record, so the same reader
|
|
73
|
+
* works for optional flags.
|
|
74
|
+
* @defaultValue `undefined`, which drops the record
|
|
75
|
+
*/
|
|
76
|
+
readonly onSources?: (sources: SourcesOf<F>) => void;
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* Evaluate a record of flag definitions and return the resolved values.
|
|
80
|
+
*
|
|
81
|
+
* The record is compiled into an anonymous command schema with no positional
|
|
82
|
+
* arguments, parsed once, and run through the CLI, env, config, prompt, default
|
|
83
|
+
* resolution chain. Aliases, negated spellings, duplicate policy, case parity,
|
|
84
|
+
* unknown-flag rejection, coercion, constraints, Standard Schema validators, and
|
|
85
|
+
* `flag.path()` checks behave exactly as they do inside a command.
|
|
86
|
+
*
|
|
87
|
+
* A pre-separator `--help` or `-h` prints generated help to the adapter's
|
|
88
|
+
* stdout and exits with code 0, unless {@linkcode ReadFlagsOptions.help} is
|
|
89
|
+
* `'off'` or a definition claims either spelling. With
|
|
90
|
+
* {@linkcode ReadFlagsOptions.strict} set to `false`, undeclared argv content
|
|
91
|
+
* is dropped instead of rejected, so a script can read its own flags out of an
|
|
92
|
+
* argv it shares with another consumer.
|
|
93
|
+
*
|
|
94
|
+
* Anything the caller leaves out comes from the runtime adapter, which is built
|
|
95
|
+
* on first use, so a call given `argv` and `env` reads nothing from the host
|
|
96
|
+
* unless a `flag.path()` check needs the adapter's filesystem primitives.
|
|
97
|
+
* `config` has no application name to discover a file from and stays
|
|
98
|
+
* caller-supplied. `prompter` stays caller-supplied as well, so a `.prompt()`
|
|
99
|
+
* flag with no prompter falls through to its default.
|
|
100
|
+
*
|
|
101
|
+
* @param definitions - Flag builders keyed by canonical flag name.
|
|
102
|
+
* @param options - Injected runtime state and behavior toggles.
|
|
103
|
+
* @returns The resolved flag values, typed from the definitions.
|
|
104
|
+
* @throws {ParseError} For unknown flags, missing values, and bad input.
|
|
105
|
+
* @throws {ValidationError} For missing required flags and failed validators.
|
|
106
|
+
* @throws {CLIError} With code `'FLAG_NAME_COLLISION'` when two definitions share
|
|
107
|
+
* a name, an alias, or a negated spelling.
|
|
108
|
+
* @throws {CLIError} With code `'INVALID_SCHEMA'` for the definition key
|
|
109
|
+
* `__proto__`, which JavaScript cannot carry as a plain record key, and for a
|
|
110
|
+
* definitions record whose prototype is replaced, which hides the entries a
|
|
111
|
+
* key check would read.
|
|
112
|
+
*
|
|
113
|
+
* @example
|
|
114
|
+
* ```ts
|
|
115
|
+
* import { flag, readFlags } from '@kjanat/dreamcli';
|
|
116
|
+
*
|
|
117
|
+
* const options = await readFlags({
|
|
118
|
+
* watch: flag.boolean().alias('w').env('WATCH').default(false),
|
|
119
|
+
* minify: flag.boolean().env('MINIFY').default(true),
|
|
120
|
+
* target: flag.enum(['node', 'browser']).env('TARGET').default('node'),
|
|
121
|
+
* });
|
|
122
|
+
*
|
|
123
|
+
* options.watch; // boolean
|
|
124
|
+
* options.minify; // boolean
|
|
125
|
+
* options.target; // 'node' | 'browser'
|
|
126
|
+
* ```
|
|
127
|
+
*
|
|
128
|
+
* @example
|
|
129
|
+
* ```ts
|
|
130
|
+
* const values = await readFlags(
|
|
131
|
+
* { watch: flag.boolean().alias('w').env('WATCH') },
|
|
132
|
+
* { argv: [], env: { WATCH: 'true' } },
|
|
133
|
+
* );
|
|
134
|
+
*
|
|
135
|
+
* values.watch; // true
|
|
136
|
+
* ```
|
|
137
|
+
*
|
|
138
|
+
* @example
|
|
139
|
+
* ```ts
|
|
140
|
+
* const values = await readFlags(
|
|
141
|
+
* { watch: flag.boolean() },
|
|
142
|
+
* { argv: ['build', '--watch', '--unknown'], env: {}, strict: false },
|
|
143
|
+
* );
|
|
144
|
+
*
|
|
145
|
+
* values.watch; // true, with 'build' and '--unknown' dropped
|
|
146
|
+
* ```
|
|
147
|
+
*/
|
|
148
|
+
declare function readFlags<const F extends FlagMap>(definitions: F, options?: ReadFlagsOptions<F>): Promise<InferFlags<F>>;
|
|
149
|
+
//#endregion
|
|
150
|
+
export { type FlagMap, type ReadFlagsOptions, readFlags };
|
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
import { CLIError } from "../errors/index.mjs";
|
|
2
|
+
import { invocationSelectsStdin } from "../schema/source.mjs";
|
|
3
|
+
import { createCommandSchema } from "../schema/command.mjs";
|
|
4
|
+
import { buildFlagLookup, flagExpectsValue, parse, requestsHelp, tokenize } from "../parse/index.mjs";
|
|
5
|
+
import { formatHelp } from "../help/index.mjs";
|
|
6
|
+
import { resolve } from "../resolve/index.mjs";
|
|
7
|
+
import { createAdapter } from "../../runtime/auto.mjs";
|
|
8
|
+
//#region src/core/read-flags/index.ts
|
|
9
|
+
/**
|
|
10
|
+
* Standalone typed flag evaluation over the existing builder DSL.
|
|
11
|
+
*
|
|
12
|
+
* {@linkcode readFlags} runs a record of {@linkcode FlagBuilder} definitions through
|
|
13
|
+
* the same command schema, parser, coercion, resolver, and validation that a
|
|
14
|
+
* command uses, and returns the values typed by {@linkcode InferFlags}. There is
|
|
15
|
+
* no command dispatch here; parse and resolution failures propagate as the
|
|
16
|
+
* framework's `ParseError` and `ValidationError`. The one output surface is the
|
|
17
|
+
* built-in `--help`: while it is on and no definition claims its spellings, a
|
|
18
|
+
* pre-separator `--help` or `-h` prints generated help to the adapter's stdout
|
|
19
|
+
* and exits the process with code 0.
|
|
20
|
+
*
|
|
21
|
+
* @module dreamcli/core/read-flags
|
|
22
|
+
*/
|
|
23
|
+
const INTERNAL_COMMAND_NAME = "<standalone>";
|
|
24
|
+
/**
|
|
25
|
+
* Reader that yields the injected adapter, or builds one the first time a fact
|
|
26
|
+
* the caller did not supply is actually needed.
|
|
27
|
+
*/
|
|
28
|
+
function adapterReader(injected) {
|
|
29
|
+
let adapter = injected;
|
|
30
|
+
return () => {
|
|
31
|
+
adapter ??= createAdapter();
|
|
32
|
+
return adapter;
|
|
33
|
+
};
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* The final path segment of the adapter's script entry, for the help usage
|
|
37
|
+
* line. Falls back to `script` when the adapter carries no script path.
|
|
38
|
+
*/
|
|
39
|
+
function scriptName(adapter) {
|
|
40
|
+
const path = adapter.argv[1] ?? "";
|
|
41
|
+
const base = path.slice(Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\")) + 1);
|
|
42
|
+
return base === "" ? "script" : base;
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Drop argv entries the lookup does not declare: unknown long flags with their
|
|
46
|
+
* inline value, unknown characters inside a short group, positional arguments,
|
|
47
|
+
* and the `--` separator. The walk mirrors the parser's value consumption, so
|
|
48
|
+
* the token after a declared value-expecting flag survives as that flag's
|
|
49
|
+
* value while the token after an unknown flag is dropped as a positional.
|
|
50
|
+
*/
|
|
51
|
+
function withoutUndeclaredTokens(argv, lookup) {
|
|
52
|
+
const tokens = tokenize(argv);
|
|
53
|
+
const kept = [];
|
|
54
|
+
let i = 0;
|
|
55
|
+
while (i < tokens.length) {
|
|
56
|
+
const token = tokens[i];
|
|
57
|
+
const raw = argv[i];
|
|
58
|
+
if (token === void 0 || raw === void 0) break;
|
|
59
|
+
if (token.kind === "positional" || token.kind === "separator") {
|
|
60
|
+
i++;
|
|
61
|
+
continue;
|
|
62
|
+
}
|
|
63
|
+
if (token.kind === "long-flag") {
|
|
64
|
+
const entry = lookup.get(token.name);
|
|
65
|
+
i++;
|
|
66
|
+
if (entry === void 0) continue;
|
|
67
|
+
kept.push(raw);
|
|
68
|
+
if (!entry.negated && token.value === void 0 && flagExpectsValue(entry.schema)) {
|
|
69
|
+
const nextRaw = argv[i];
|
|
70
|
+
if (tokens[i]?.kind === "positional" && nextRaw !== void 0) {
|
|
71
|
+
kept.push(nextRaw);
|
|
72
|
+
i++;
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
continue;
|
|
76
|
+
}
|
|
77
|
+
let declared = "";
|
|
78
|
+
let awaitsValue = false;
|
|
79
|
+
for (let ci = 0; ci < token.chars.length; ci++) {
|
|
80
|
+
const ch = token.chars.charAt(ci);
|
|
81
|
+
const entry = lookup.get(ch);
|
|
82
|
+
if (entry === void 0) continue;
|
|
83
|
+
declared += ch;
|
|
84
|
+
if (flagExpectsValue(entry.schema)) {
|
|
85
|
+
const inline = token.chars.slice(ci + 1);
|
|
86
|
+
if (inline.length > 0) declared += inline;
|
|
87
|
+
else awaitsValue = true;
|
|
88
|
+
break;
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
i++;
|
|
92
|
+
if (declared.length === 0) continue;
|
|
93
|
+
kept.push(`-${declared}`);
|
|
94
|
+
if (awaitsValue) {
|
|
95
|
+
const nextRaw = argv[i];
|
|
96
|
+
if (tokens[i]?.kind === "positional" && nextRaw !== void 0) {
|
|
97
|
+
kept.push(nextRaw);
|
|
98
|
+
i++;
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
return kept;
|
|
103
|
+
}
|
|
104
|
+
/**
|
|
105
|
+
* Evaluate a record of flag definitions and return the resolved values.
|
|
106
|
+
*
|
|
107
|
+
* The record is compiled into an anonymous command schema with no positional
|
|
108
|
+
* arguments, parsed once, and run through the CLI, env, config, prompt, default
|
|
109
|
+
* resolution chain. Aliases, negated spellings, duplicate policy, case parity,
|
|
110
|
+
* unknown-flag rejection, coercion, constraints, Standard Schema validators, and
|
|
111
|
+
* `flag.path()` checks behave exactly as they do inside a command.
|
|
112
|
+
*
|
|
113
|
+
* A pre-separator `--help` or `-h` prints generated help to the adapter's
|
|
114
|
+
* stdout and exits with code 0, unless {@linkcode ReadFlagsOptions.help} is
|
|
115
|
+
* `'off'` or a definition claims either spelling. With
|
|
116
|
+
* {@linkcode ReadFlagsOptions.strict} set to `false`, undeclared argv content
|
|
117
|
+
* is dropped instead of rejected, so a script can read its own flags out of an
|
|
118
|
+
* argv it shares with another consumer.
|
|
119
|
+
*
|
|
120
|
+
* Anything the caller leaves out comes from the runtime adapter, which is built
|
|
121
|
+
* on first use, so a call given `argv` and `env` reads nothing from the host
|
|
122
|
+
* unless a `flag.path()` check needs the adapter's filesystem primitives.
|
|
123
|
+
* `config` has no application name to discover a file from and stays
|
|
124
|
+
* caller-supplied. `prompter` stays caller-supplied as well, so a `.prompt()`
|
|
125
|
+
* flag with no prompter falls through to its default.
|
|
126
|
+
*
|
|
127
|
+
* @param definitions - Flag builders keyed by canonical flag name.
|
|
128
|
+
* @param options - Injected runtime state and behavior toggles.
|
|
129
|
+
* @returns The resolved flag values, typed from the definitions.
|
|
130
|
+
* @throws {ParseError} For unknown flags, missing values, and bad input.
|
|
131
|
+
* @throws {ValidationError} For missing required flags and failed validators.
|
|
132
|
+
* @throws {CLIError} With code `'FLAG_NAME_COLLISION'` when two definitions share
|
|
133
|
+
* a name, an alias, or a negated spelling.
|
|
134
|
+
* @throws {CLIError} With code `'INVALID_SCHEMA'` for the definition key
|
|
135
|
+
* `__proto__`, which JavaScript cannot carry as a plain record key, and for a
|
|
136
|
+
* definitions record whose prototype is replaced, which hides the entries a
|
|
137
|
+
* key check would read.
|
|
138
|
+
*
|
|
139
|
+
* @example
|
|
140
|
+
* ```ts
|
|
141
|
+
* import { flag, readFlags } from '@kjanat/dreamcli';
|
|
142
|
+
*
|
|
143
|
+
* const options = await readFlags({
|
|
144
|
+
* watch: flag.boolean().alias('w').env('WATCH').default(false),
|
|
145
|
+
* minify: flag.boolean().env('MINIFY').default(true),
|
|
146
|
+
* target: flag.enum(['node', 'browser']).env('TARGET').default('node'),
|
|
147
|
+
* });
|
|
148
|
+
*
|
|
149
|
+
* options.watch; // boolean
|
|
150
|
+
* options.minify; // boolean
|
|
151
|
+
* options.target; // 'node' | 'browser'
|
|
152
|
+
* ```
|
|
153
|
+
*
|
|
154
|
+
* @example
|
|
155
|
+
* ```ts
|
|
156
|
+
* const values = await readFlags(
|
|
157
|
+
* { watch: flag.boolean().alias('w').env('WATCH') },
|
|
158
|
+
* { argv: [], env: { WATCH: 'true' } },
|
|
159
|
+
* );
|
|
160
|
+
*
|
|
161
|
+
* values.watch; // true
|
|
162
|
+
* ```
|
|
163
|
+
*
|
|
164
|
+
* @example
|
|
165
|
+
* ```ts
|
|
166
|
+
* const values = await readFlags(
|
|
167
|
+
* { watch: flag.boolean() },
|
|
168
|
+
* { argv: ['build', '--watch', '--unknown'], env: {}, strict: false },
|
|
169
|
+
* );
|
|
170
|
+
*
|
|
171
|
+
* values.watch; // true, with 'build' and '--unknown' dropped
|
|
172
|
+
* ```
|
|
173
|
+
*/
|
|
174
|
+
async function readFlags(definitions, options) {
|
|
175
|
+
for (const key of Reflect.ownKeys(definitions)) if (typeof key !== "string" || !Object.prototype.propertyIsEnumerable.call(definitions, key)) throw new CLIError("Flag definitions must use enumerable string keys", { code: "INVALID_SCHEMA" });
|
|
176
|
+
const prototype = Object.getPrototypeOf(definitions);
|
|
177
|
+
if (prototype !== Object.prototype && prototype !== null) throw new CLIError("Flag definitions record has a replaced prototype. A '__proto__' key sets the prototype instead of adding a definition, and an inherited definition is never read", {
|
|
178
|
+
code: "INVALID_SCHEMA",
|
|
179
|
+
suggest: "Pass a plain object with no '__proto__' key, or a record built with Object.create(null)"
|
|
180
|
+
});
|
|
181
|
+
const entries = Object.entries(definitions);
|
|
182
|
+
for (const [name] of entries) if (name === "__proto__") throw new CLIError(`Flag name '${name}' is not usable as a flag`, {
|
|
183
|
+
code: "INVALID_SCHEMA",
|
|
184
|
+
details: { flag: name },
|
|
185
|
+
suggest: "Rename the definition key, for example to \"proto\""
|
|
186
|
+
});
|
|
187
|
+
const flags = Object.fromEntries(entries.map(([name, builder]) => [name, builder.schema]));
|
|
188
|
+
const schema = createCommandSchema({
|
|
189
|
+
name: INTERNAL_COMMAND_NAME,
|
|
190
|
+
flags
|
|
191
|
+
});
|
|
192
|
+
const host = adapterReader(options?.adapter);
|
|
193
|
+
const argv = options?.argv ?? host().argv.slice(2);
|
|
194
|
+
const lookup = buildFlagLookup(schema.flags, options?.parse);
|
|
195
|
+
if ((options?.help ?? "on") === "on" && !lookup.has("help") && !lookup.has("h") && requestsHelp(argv)) {
|
|
196
|
+
host().stdout(formatHelp(schema, {
|
|
197
|
+
binName: scriptName(host()),
|
|
198
|
+
isDefaultHelp: true
|
|
199
|
+
}));
|
|
200
|
+
host().exit(0);
|
|
201
|
+
}
|
|
202
|
+
const parsed = parse(schema, options?.strict === false ? withoutUndeclaredTokens(argv, lookup) : argv, options?.parse);
|
|
203
|
+
const stdinData = options?.stdinData === void 0 && invocationSelectsStdin(schema.flags, schema.args, parsed) ? await host().readStdin() : options?.stdinData;
|
|
204
|
+
const resolved = await resolve(schema, parsed, {
|
|
205
|
+
env: options?.env ?? host().env,
|
|
206
|
+
stat: options?.stat ?? ((path) => host().stat(path)),
|
|
207
|
+
mkdir: options?.mkdir ?? ((path) => host().mkdir(path)),
|
|
208
|
+
...options?.config !== void 0 ? { config: options.config } : {},
|
|
209
|
+
...options?.prompter !== void 0 ? { prompter: options.prompter } : {},
|
|
210
|
+
...stdinData !== void 0 ? { stdinData } : {}
|
|
211
|
+
});
|
|
212
|
+
for (const warning of resolved.deprecations) options?.onDeprecation?.(warning);
|
|
213
|
+
options?.onSources?.(resolved.provenance.flags);
|
|
214
|
+
return resolved.flags;
|
|
215
|
+
}
|
|
216
|
+
//#endregion
|
|
217
|
+
export { readFlags };
|
|
@@ -1,8 +1,39 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { ResolutionProvenance } from "../schema/provenance.mjs";
|
|
2
2
|
import { CommandArgEntry } from "../schema/command.mjs";
|
|
3
|
+
import { PromptEngine } from "../prompt/index.mjs";
|
|
3
4
|
import "../schema/index.mjs";
|
|
5
|
+
import { DeprecationWarning } from "./contracts.mjs";
|
|
6
|
+
import { MkdirFn, StatFn } from "./path-checks.mjs";
|
|
4
7
|
//#region src/core/resolve/args.d.ts
|
|
5
|
-
/**
|
|
6
|
-
|
|
8
|
+
/** External state and collectors one arg-resolution pass shares. */
|
|
9
|
+
interface ArgResolutionOptions {
|
|
10
|
+
/** Environment variable snapshot. */
|
|
11
|
+
readonly env: Readonly<Record<string, string | undefined>>;
|
|
12
|
+
/** Parsed config file contents. */
|
|
13
|
+
readonly config: Readonly<Record<string, unknown>>;
|
|
14
|
+
/** Pre-read stdin content, or `null`/`undefined` when nothing was piped. */
|
|
15
|
+
readonly stdinData: string | null | undefined;
|
|
16
|
+
/** Interactive prompt engine, absent in non-TTY contexts. */
|
|
17
|
+
readonly prompter: PromptEngine | undefined;
|
|
18
|
+
/** Collector for notices produced by `.deprecated()` args. */
|
|
19
|
+
readonly deprecations: DeprecationWarning[];
|
|
20
|
+
/** Filesystem probe for `arg.path()` checks. */
|
|
21
|
+
readonly stat: StatFn | undefined;
|
|
22
|
+
/** Directory creation for `arg.path()` `create` checks. */
|
|
23
|
+
readonly mkdir: MkdirFn | undefined;
|
|
24
|
+
/** Receiver for the stage that produced each resolved arg. */
|
|
25
|
+
readonly provenance: Record<string, ResolutionProvenance>;
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* Walk every declared arg through the resolution chain
|
|
29
|
+
* (cli -> stdin -> env -> config -> prompt -> default), collecting deprecations
|
|
30
|
+
* and throwing aggregated errors.
|
|
31
|
+
*
|
|
32
|
+
* @param argEntries - Declared positionals in CLI order.
|
|
33
|
+
* @param parsedArgs - Values the parser read off argv.
|
|
34
|
+
* @param options - External state and collectors for this pass.
|
|
35
|
+
* @returns Fully resolved arg values keyed by arg name.
|
|
36
|
+
*/
|
|
37
|
+
declare function resolveArgs(argEntries: readonly CommandArgEntry[], parsedArgs: Readonly<Record<string, unknown>>, options: ArgResolutionOptions): Promise<Readonly<Record<string, unknown>>>;
|
|
7
38
|
//#endregion
|
|
8
|
-
export { resolveArgs };
|
|
39
|
+
export { type ArgResolutionOptions, resolveArgs };
|