@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,17 @@
1
+ //#region src/core/schema/brand.d.ts
2
+ /**
3
+ * Type-only seal for framework-normalized schema values.
4
+ *
5
+ * The symbol has no runtime value: schema objects never carry the key, so
6
+ * spreads, `structuredClone`, and JSON round-trips are unaffected. The brand
7
+ * exists purely in the type system — consumers cannot spell the key, so a
8
+ * structural literal is never assignable to a sealed schema type, and the
9
+ * normalization factories are the only construction path.
10
+ *
11
+ * @module dreamcli/core/schema/brand
12
+ */
13
+ declare const schemaBrand: unique symbol;
14
+ /** Discriminator literals carried by the sealed schema types. */
15
+ type SchemaBrandKind = "flag" | "arg" | "command" | "cli" | "config" | "builtins";
16
+ //#endregion
17
+ export type { SchemaBrandKind, schemaBrand };
@@ -0,0 +1,301 @@
1
+ import { StandardSchemaV1 } from "./standard.mjs";
2
+ import { FlagSchema } from "./flag.mjs";
3
+ import { ValueFailure, ValueSchema } from "./value.mjs";
4
+ import { ArgSchema } from "./arg.mjs";
5
+ //#region src/core/schema/cardinality.d.ts
6
+ /** All split formats as a runtime array. */
7
+ declare const SPLIT_FORMATS: readonly ["whole", "delimiter", "lines", "json"];
8
+ /** How one source's text decodes into collection elements. */
9
+ type SplitFormat = (typeof SPLIT_FORMATS)[number];
10
+ /**
11
+ * How one source's text decodes into collection elements.
12
+ *
13
+ * - `'whole'`: the source value is a single element
14
+ * - `'delimiter'`: split on a literal delimiter, dropping empty segments
15
+ * - `'lines'`: split on `\n`, `\r\n`, or `\r`
16
+ * - `'json'`: parse the text as JSON
17
+ */
18
+ type SplitPolicy = {
19
+ readonly format: "whole";
20
+ } | {
21
+ readonly format: "delimiter";
22
+ readonly delimiter: string;
23
+ } | {
24
+ readonly format: "lines";
25
+ } | {
26
+ readonly format: "json";
27
+ };
28
+ /**
29
+ * A split policy, a format name, or a literal delimiter.
30
+ *
31
+ * The strings `'whole'`, `'lines'`, and `'json'` name their format; every other
32
+ * string is the delimiter to split on, so `','` is the comma policy.
33
+ */
34
+ type SplitSetting = string | SplitPolicy;
35
+ /**
36
+ * Per-source split settings accepted by `.split()`.
37
+ *
38
+ * Config values are native arrays and objects; a config string decodes under
39
+ * the `env` policy.
40
+ */
41
+ interface SplitOptions {
42
+ /**
43
+ * How each CLI token splits. Accepts `'whole'` and a delimiter.
44
+ * @defaultValue `'whole'`, or the delimiter set by `.separator()`
45
+ */
46
+ readonly cli?: SplitSetting | undefined;
47
+ /**
48
+ * How an environment value splits. Accepts `'whole'`, `'json'`, and a delimiter.
49
+ * @defaultValue `{ format: 'delimiter', delimiter: ',' }`
50
+ */
51
+ readonly env?: SplitSetting | undefined;
52
+ /**
53
+ * How the stdin buffer splits. Accepts every format.
54
+ * @defaultValue `'lines'`
55
+ */
56
+ readonly stdin?: SplitSetting | undefined;
57
+ }
58
+ /**
59
+ * The non-CLI split policies a schema stores.
60
+ *
61
+ * The CLI delimiter lives on the `separator` field both schemas already carry,
62
+ * so `.separator(',')` and `.split({ cli: ',' })` write the same place.
63
+ */
64
+ interface SourceSplitBinding {
65
+ /** Environment split policy, or `undefined` for the default. */
66
+ readonly env: SplitPolicy | undefined;
67
+ /** Stdin split policy, or `undefined` for the default. */
68
+ readonly stdin: SplitPolicy | undefined;
69
+ }
70
+ /** The resolved split policy of every source. */
71
+ interface SplitBinding {
72
+ /** How each CLI token splits. */
73
+ readonly cli: SplitPolicy;
74
+ /** How an environment value splits. */
75
+ readonly env: SplitPolicy;
76
+ /** How the stdin buffer splits. */
77
+ readonly stdin: SplitPolicy;
78
+ }
79
+ /**
80
+ * Normalize one source's split setting.
81
+ *
82
+ * @param source - Which source the setting belongs to.
83
+ * @param setting - The policy, a format name, or a delimiter.
84
+ * @returns The normalized policy.
85
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on a format the source does
86
+ * not accept, or an empty delimiter.
87
+ */
88
+ declare function normalizeSplitPolicy(source: keyof SplitOptions, setting: SplitSetting): SplitPolicy;
89
+ /** One source's split setting, split into the CLI carrier and the rest. */
90
+ interface NormalizedSplitOptions {
91
+ /** The CLI delimiter, or `undefined` when CLI tokens stay whole. */
92
+ readonly separator: string | undefined;
93
+ /** Whether the options named the CLI source at all. */
94
+ readonly setsSeparator: boolean;
95
+ /** The stored non-CLI policies. */
96
+ readonly split: SourceSplitBinding | undefined;
97
+ }
98
+ /**
99
+ * Normalize `.split()` options into the fields a schema stores.
100
+ *
101
+ * A source the options leave out keeps the policy already stored, so successive
102
+ * `.split()` calls each set one source instead of clearing the others.
103
+ *
104
+ * @param options - Per-source split settings.
105
+ * @param stored - The binding already on the schema, when there is one.
106
+ * @returns The CLI delimiter and the stored non-CLI binding.
107
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on a format a source does not
108
+ * accept, or an empty delimiter.
109
+ */
110
+ declare function normalizeSplitOptions(options: SplitOptions, stored?: SourceSplitBinding | undefined): NormalizedSplitOptions;
111
+ /**
112
+ * Resolve the split policy of every source from the stored fields.
113
+ *
114
+ * @param separator - The CLI delimiter carrier.
115
+ * @param split - The stored non-CLI policies.
116
+ * @returns One policy per source, defaults filled in.
117
+ */
118
+ declare function splitBindingOf(separator: string | undefined, split: SourceSplitBinding | undefined): SplitBinding;
119
+ /** All duplicate-key policies as a runtime array. */
120
+ declare const DUPLICATE_KEYS: readonly ["first", "last", "error"];
121
+ /**
122
+ * How a repeated key combines when entries aggregate.
123
+ *
124
+ * - `'last'`: the later occurrence wins
125
+ * - `'first'`: the earlier occurrence wins
126
+ * - `'error'`: a repeat is a validation failure
127
+ *
128
+ * @defaultValue `'last'`
129
+ */
130
+ type DuplicateKeys = (typeof DUPLICATE_KEYS)[number];
131
+ /**
132
+ * How many values an input carries and how they combine.
133
+ *
134
+ * `'one'` is a single value; `'many'` an ordered array; `'entries'` a key/value
135
+ * record; `'count'` the number of CLI occurrences.
136
+ */
137
+ type Cardinality = {
138
+ readonly kind: "one";
139
+ } | {
140
+ readonly kind: "many";
141
+ readonly unique: boolean;
142
+ readonly cliSplit: SplitPolicy;
143
+ } | {
144
+ readonly kind: "entries";
145
+ readonly duplicateKeys: DuplicateKeys;
146
+ readonly cliSplit: SplitPolicy;
147
+ } | {
148
+ readonly kind: "count";
149
+ };
150
+ /**
151
+ * Project a flag schema onto its cardinality axis.
152
+ *
153
+ * @param schema - The flag schema to read.
154
+ * @returns How the flag's values combine.
155
+ */
156
+ declare function flagCardinality(schema: FlagSchema): Cardinality;
157
+ /**
158
+ * Project an arg schema onto its cardinality axis.
159
+ *
160
+ * A `keyValue` arg aggregates entries whether or not it is variadic: the
161
+ * non-variadic form reads one `k=v` token, the variadic form the whole tail.
162
+ *
163
+ * @param schema - The arg schema to read.
164
+ * @returns How the arg's values combine.
165
+ */
166
+ declare function argCardinality(schema: ArgSchema): Cardinality;
167
+ /** Whether a cardinality aggregates several values. */
168
+ declare function isCollection(cardinality: Cardinality): cardinality is Extract<Cardinality, {
169
+ readonly kind: "many" | "entries";
170
+ }>;
171
+ /** Why a source's text could not be split into elements. */
172
+ type SplitFailure = {
173
+ readonly kind: "json";
174
+ readonly error: unknown;
175
+ } | {
176
+ readonly kind: "json-shape";
177
+ readonly expected: "array" | "object";
178
+ } | {
179
+ readonly kind: "pair";
180
+ readonly raw: string;
181
+ };
182
+ /** Elements read out of one source, or why the text was unreadable. */
183
+ type SplitResult<T> = {
184
+ readonly ok: true;
185
+ readonly parts: readonly T[];
186
+ } | {
187
+ readonly ok: false;
188
+ readonly failure: SplitFailure;
189
+ };
190
+ /**
191
+ * Split text into the elements of a `many` collection.
192
+ *
193
+ * @param policy - The source's split policy.
194
+ * @param text - The raw source text.
195
+ * @returns The elements, or why the text was unreadable.
196
+ */
197
+ declare function splitManyText(policy: SplitPolicy, text: string): SplitResult<unknown>;
198
+ /**
199
+ * Split text into the pairs of an `entries` collection.
200
+ *
201
+ * Delimited and line-separated text carries `KEY=VALUE` segments split at the
202
+ * first `=`; JSON text carries an object.
203
+ *
204
+ * @param policy - The source's split policy.
205
+ * @param text - The raw source text.
206
+ * @returns The pairs, or why the text was unreadable.
207
+ */
208
+ declare function splitEntriesText(policy: SplitPolicy, text: string): SplitResult<readonly [string, unknown]>;
209
+ /**
210
+ * Split one `KEY=VALUE` token at the first `=`.
211
+ *
212
+ * @param raw - The token to split.
213
+ * @returns The pair, or `undefined` when the token has no `=` or an empty key.
214
+ */
215
+ declare function splitEntryPair(raw: string): readonly [string, string] | undefined;
216
+ /**
217
+ * Split text on line terminators.
218
+ *
219
+ * A final terminator frames the last line rather than starting an empty one, so
220
+ * the single empty element it produces is removed and genuine blank lines
221
+ * survive: `'a\nb\n'` gives `['a', 'b']` and `'a\nb\n\n'` gives `['a', 'b', '']`.
222
+ *
223
+ * @param text - The raw source text.
224
+ * @returns One element per line.
225
+ */
226
+ declare function splitLines(text: string): readonly string[];
227
+ /** Deduplicate a resolved array, preserving first-seen order. */
228
+ declare function dedupe(values: readonly unknown[]): readonly unknown[];
229
+ /**
230
+ * The record entries folded to, or the key a duplicate policy rejected.
231
+ *
232
+ * `at` is the index of the repeating pair, so a caller that knows where each
233
+ * pair came from can name that source in its diagnostic.
234
+ */
235
+ type FoldResult = {
236
+ readonly ok: true;
237
+ readonly value: Readonly<Record<string, unknown>>;
238
+ } | {
239
+ readonly ok: false;
240
+ readonly duplicateKey: string;
241
+ readonly at: number;
242
+ };
243
+ /**
244
+ * Fold ordered pairs into a record under a duplicate-key policy.
245
+ *
246
+ * `Object.fromEntries` defines own data properties, so a `'__proto__'` key is
247
+ * stored verbatim instead of reaching the prototype setter.
248
+ *
249
+ * @param pairs - The pairs in occurrence order.
250
+ * @param duplicateKeys - What a repeated key means.
251
+ * @returns The record, or the key that repeated under `'error'` and where.
252
+ */
253
+ declare function foldEntries(pairs: readonly (readonly [string, unknown])[], duplicateKeys: DuplicateKeys): FoldResult;
254
+ /** Why a declared default value is not a value the input could hold. */
255
+ type DefaultViolation = {
256
+ readonly kind: "shape";
257
+ readonly expected: "array" | "object" | "count";
258
+ } | {
259
+ readonly kind: "element";
260
+ readonly at: string | undefined;
261
+ readonly value: unknown;
262
+ readonly failure: ValueFailure;
263
+ } | {
264
+ readonly kind: "standard";
265
+ readonly at: string | undefined;
266
+ readonly value: unknown;
267
+ readonly issues: readonly string[];
268
+ };
269
+ /**
270
+ * Validate a declared default against the value and cardinality axes.
271
+ *
272
+ * A default is already the typed value, so it is validated rather than decoded.
273
+ * Only synchronous verdicts are reachable here: a Standard Schema validator
274
+ * that returns a promise is left to the resolution-time pass, as are filesystem
275
+ * checks.
276
+ *
277
+ * @param element - The value axis of each element (of the value itself for `'one'`).
278
+ * @param cardinality - How the input's values combine.
279
+ * @param aggregate - Standard Schema validator applied to the completed collection.
280
+ * @param value - The declared default.
281
+ * @returns The violation, or `undefined` when the default is valid so far.
282
+ */
283
+ declare function validateDefault(element: ValueSchema, cardinality: Cardinality, aggregate: StandardSchemaV1 | undefined, value: unknown): DefaultViolation | undefined;
284
+ /**
285
+ * The English article that precedes a kind name.
286
+ *
287
+ * @param word - The kind name a message names an input by.
288
+ * @returns `'an'` before a vowel, `'a'` otherwise.
289
+ */
290
+ declare function indefiniteArticle(word: string): string;
291
+ /**
292
+ * Build the construction-time error for a default value that cannot hold.
293
+ *
294
+ * @param subject - How the input is spelled, `--tag` or `<files>`.
295
+ * @param details - Structured identification of the input.
296
+ * @param violation - What the default failed.
297
+ * @returns The error to throw.
298
+ */
299
+ declare function defaultViolationError(subject: string, details: Readonly<Record<string, unknown>>, violation: DefaultViolation): CLIError;
300
+ //#endregion
301
+ export { type Cardinality, DUPLICATE_KEYS, type DefaultViolation, type DuplicateKeys, type FoldResult, type NormalizedSplitOptions, SPLIT_FORMATS, type SourceSplitBinding, type SplitBinding, type SplitFailure, type SplitFormat, type SplitOptions, type SplitPolicy, type SplitResult, type SplitSetting, argCardinality, dedupe, defaultViolationError, flagCardinality, foldEntries, indefiniteArticle, isCollection, normalizeSplitOptions, normalizeSplitPolicy, splitBindingOf, splitEntriesText, splitEntryPair, splitLines, splitManyText, validateDefault };