@kjanat/dreamcli 3.0.0 → 4.0.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (147) hide show
  1. package/CHANGELOG.md +967 -1
  2. package/README.md +9 -3
  3. package/dist/core/cli/builtins.d.mts +47 -0
  4. package/dist/core/cli/builtins.mjs +135 -0
  5. package/dist/core/cli/compiled.d.mts +29 -0
  6. package/dist/core/cli/compiled.mjs +76 -0
  7. package/dist/core/cli/dispatch.d.mts +9 -85
  8. package/dist/core/cli/help-links.d.mts +2 -14
  9. package/dist/core/cli/index.d.mts +282 -101
  10. package/dist/core/cli/index.mjs +497 -264
  11. package/dist/core/cli/planner.d.mts +13 -86
  12. package/dist/core/cli/planner.mjs +47 -30
  13. package/dist/core/cli/plugin.d.mts +1 -1
  14. package/dist/core/cli/propagate.mjs +1 -1
  15. package/dist/core/cli/reserved-flags.d.mts +1 -0
  16. package/dist/core/cli/reserved-flags.mjs +158 -0
  17. package/dist/core/cli/root-help.d.mts +1 -47
  18. package/dist/core/cli/root-help.mjs +37 -47
  19. package/dist/core/cli/root-output-flags.d.mts +1 -0
  20. package/dist/core/cli/root-output-flags.mjs +169 -0
  21. package/dist/core/cli/root-surface.d.mts +1 -68
  22. package/dist/core/cli/root-surface.mjs +2 -2
  23. package/dist/core/cli/runtime-preflight.d.mts +1 -199
  24. package/dist/core/cli/runtime-preflight.mjs +67 -17
  25. package/dist/core/completion/index.d.mts +2 -2
  26. package/dist/core/completion/shells/bash.d.mts +0 -1
  27. package/dist/core/completion/shells/bash.mjs +2 -1
  28. package/dist/core/completion/shells/fish.d.mts +0 -1
  29. package/dist/core/completion/shells/fish.mjs +2 -1
  30. package/dist/core/completion/shells/powershell.d.mts +0 -1
  31. package/dist/core/completion/shells/powershell.mjs +2 -1
  32. package/dist/core/completion/shells/shared.d.mts +3 -114
  33. package/dist/core/completion/shells/shared.mjs +9 -39
  34. package/dist/core/completion/shells/zsh.d.mts +0 -1
  35. package/dist/core/completion/shells/zsh.mjs +2 -1
  36. package/dist/core/config/index.d.mts +3 -3
  37. package/dist/core/config/index.mjs +2 -2
  38. package/dist/core/config/package-json.d.mts +2 -33
  39. package/dist/core/config/package-json.mjs +1 -34
  40. package/dist/core/errors/index.d.mts +7 -7
  41. package/dist/core/execution/index.d.mts +1 -48
  42. package/dist/core/execution/index.mjs +42 -27
  43. package/dist/core/help/ansi.d.mts +0 -11
  44. package/dist/core/help/index.d.mts +3 -35
  45. package/dist/core/help/index.mjs +29 -6
  46. package/dist/core/help/theme.d.mts +1 -21
  47. package/dist/core/json-schema/index.d.mts +279 -10
  48. package/dist/core/json-schema/index.mjs +482 -237
  49. package/dist/core/json-schema/meta-descriptions.generated.d.mts +79 -7
  50. package/dist/core/json-schema/meta-descriptions.generated.mjs +40 -6
  51. package/dist/core/output/activity.d.mts +1 -193
  52. package/dist/core/output/activity.mjs +1 -1
  53. package/dist/core/output/bind.d.mts +1 -37
  54. package/dist/core/output/contracts.d.mts +7 -13
  55. package/dist/core/output/contracts.mjs +1 -1
  56. package/dist/core/output/display-value.d.mts +1 -19
  57. package/dist/core/output/index.d.mts +5 -187
  58. package/dist/core/output/index.mjs +44 -9
  59. package/dist/core/output/renderers.d.mts +1 -45
  60. package/dist/core/output/writer.d.mts +0 -1
  61. package/dist/core/parse/index.d.mts +27 -5
  62. package/dist/core/parse/index.mjs +350 -227
  63. package/dist/core/parse/occurrences.d.mts +89 -0
  64. package/dist/core/parse/occurrences.mjs +114 -0
  65. package/dist/core/prompt/index.d.mts +3 -3
  66. package/dist/core/read-flags/index.d.mts +150 -0
  67. package/dist/core/read-flags/index.mjs +217 -0
  68. package/dist/core/resolve/args.d.mts +35 -4
  69. package/dist/core/resolve/args.mjs +132 -55
  70. package/dist/core/resolve/coerce.d.mts +66 -9
  71. package/dist/core/resolve/coerce.mjs +834 -270
  72. package/dist/core/resolve/config.d.mts +1 -10
  73. package/dist/core/resolve/contracts.d.mts +67 -44
  74. package/dist/core/resolve/errors.mjs +29 -21
  75. package/dist/core/resolve/flags.d.mts +36 -9
  76. package/dist/core/resolve/flags.mjs +129 -151
  77. package/dist/core/resolve/index.d.mts +8 -6
  78. package/dist/core/resolve/index.mjs +51 -18
  79. package/dist/core/resolve/path-checks.d.mts +47 -0
  80. package/dist/core/resolve/path-checks.mjs +102 -0
  81. package/dist/core/resolve/redaction.d.mts +12 -0
  82. package/dist/core/resolve/redaction.mjs +14 -0
  83. package/dist/core/resolve/stages.d.mts +85 -0
  84. package/dist/core/resolve/stages.mjs +170 -0
  85. package/dist/core/resolve/standard.d.mts +1 -24
  86. package/dist/core/resolve/standard.mjs +141 -43
  87. package/dist/core/schema/activity.d.mts +16 -16
  88. package/dist/core/schema/arg.d.mts +849 -71
  89. package/dist/core/schema/arg.mjs +727 -54
  90. package/dist/core/schema/brand.d.mts +17 -0
  91. package/dist/core/schema/cardinality.d.mts +301 -0
  92. package/dist/core/schema/cardinality.mjs +514 -0
  93. package/dist/core/schema/command.d.mts +181 -112
  94. package/dist/core/schema/command.mjs +305 -42
  95. package/dist/core/schema/flag.d.mts +515 -173
  96. package/dist/core/schema/flag.mjs +576 -78
  97. package/dist/core/schema/index.d.mts +11 -8
  98. package/dist/core/schema/index.mjs +10 -0
  99. package/dist/core/schema/middleware.d.mts +15 -12
  100. package/dist/core/schema/number-constraints.d.mts +5 -5
  101. package/dist/core/schema/prompt.d.mts +4 -4
  102. package/dist/core/schema/provenance.d.mts +99 -0
  103. package/dist/core/schema/provenance.mjs +28 -0
  104. package/dist/core/schema/run.d.mts +21 -60
  105. package/dist/core/schema/source.d.mts +179 -0
  106. package/dist/core/schema/source.mjs +206 -0
  107. package/dist/core/schema/standard.d.mts +12 -19
  108. package/dist/core/schema/stdin.d.mts +87 -0
  109. package/dist/core/schema/stdin.mjs +91 -0
  110. package/dist/core/schema/string-constraints.d.mts +16 -5
  111. package/dist/core/schema/string-constraints.mjs +18 -1
  112. package/dist/core/schema/value-parsers.d.mts +81 -9
  113. package/dist/core/schema/value-parsers.mjs +19 -1
  114. package/dist/core/schema/value.d.mts +242 -0
  115. package/dist/core/schema/value.mjs +573 -0
  116. package/dist/core/testkit/index.d.mts +28 -3
  117. package/dist/core/testkit/index.mjs +40 -26
  118. package/dist/index.d.mts +21 -16
  119. package/dist/index.mjs +10 -6
  120. package/dist/runtime/adapter.d.mts +3 -3
  121. package/dist/runtime/deno.d.mts +3 -3
  122. package/dist/runtime/detect.d.mts +2 -2
  123. package/dist/runtime/node.d.mts +3 -3
  124. package/dist/runtime/paths.d.mts +1 -31
  125. package/dist/runtime.d.mts +4 -4
  126. package/dist/strings.d.mts +1 -16
  127. package/dist/testkit.d.mts +2 -2
  128. package/dist/testkit.mjs +1 -1
  129. package/dist/version.d.mts +0 -13
  130. package/dist/version.mjs +2 -2
  131. package/dreamcli.schema.json +368 -78
  132. package/examples/interactive.ts +6 -5
  133. package/package.json +10 -9
  134. package/skills/cli-creation/SKILL.md +196 -0
  135. package/skills/cli-creation/agents/openai.yaml +4 -0
  136. package/skills/cli-creation/assets/templates/multi-command.bun-test.ts.tpl +20 -0
  137. package/skills/cli-creation/assets/templates/multi-command.test.ts.tpl +20 -0
  138. package/skills/cli-creation/assets/templates/multi-command.ts.tpl +89 -0
  139. package/skills/cli-creation/assets/templates/single-command.bun-test.ts.tpl +29 -0
  140. package/skills/cli-creation/assets/templates/single-command.test.ts.tpl +29 -0
  141. package/skills/cli-creation/assets/templates/single-command.ts.tpl +47 -0
  142. package/skills/cli-creation/references/consumer-workflow.md +65 -0
  143. package/skills/cli-creation/references/pattern-cookbook.md +451 -0
  144. package/skills/cli-creation/references/runtime-notes.md +29 -0
  145. package/skills/cli-creation/scripts/scaffold_cli.py +360 -0
  146. package/dist/core/resolve/property.d.mts +0 -51
  147. 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: 'select';
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: 'multiselect';
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?: 'throw' | 'cancel';
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 { DeprecationWarning } from "./contracts.mjs";
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
- /** Walk every declared arg through the resolution chain (cli -> stdin -> env -> default), collecting deprecations and throwing aggregated errors. */
6
- declare function resolveArgs(argEntries: readonly CommandArgEntry[], parsedArgs: Readonly<Record<string, unknown>>, stdinData: string | null | undefined, env: Readonly<Record<string, string | undefined>>, deprecations: DeprecationWarning[]): Readonly<Record<string, unknown>>;
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 };