@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
@@ -138,5 +138,23 @@ function parseBytesValue(raw) {
138
138
  if (scale === void 0) throw new Error(`Invalid size '${raw}': unknown unit '${match[2] ?? ""}'`);
139
139
  return Math.round(Number(match[1]) * scale);
140
140
  }
141
+ /**
142
+ * Normalize path factory options into the {@link PathChecks} a schema stores.
143
+ *
144
+ * Options that ask for nothing (absent, `{}`, or `mustExist: false` alone)
145
+ * produce `undefined`, so the schema records no checks and the resolver skips
146
+ * the filesystem entirely.
147
+ *
148
+ * @param options - Options passed to `flag.path()` or `arg.path()`.
149
+ * @returns The checks to store, or `undefined` when none were requested.
150
+ */
151
+ function buildPathChecks(options) {
152
+ if (options === void 0 || options.mustExist !== true && options.type === void 0) return;
153
+ return {
154
+ mustExist: options.mustExist ?? true,
155
+ type: options.type,
156
+ create: options.type === "directory" && options.create === true
157
+ };
158
+ }
141
159
  //#endregion
142
- export { parseBytesValue, parseDateValue, parseDurationValue, parseUrlValue };
160
+ export { buildPathChecks, parseBytesValue, parseDateValue, parseDurationValue, parseUrlValue };
@@ -0,0 +1,242 @@
1
+ import { NumberConstraintViolation, NumberConstraints } from "./number-constraints.mjs";
2
+ import { StandardSchemaV1 } from "./standard.mjs";
3
+ import { StringConstraintViolation, StringConstraints } from "./string-constraints.mjs";
4
+ import { DateFlagOptions, PathChecks, PathFlagOptions, UrlFlagOptions } from "./value-parsers.mjs";
5
+ import { FlagSchema } from "./flag.mjs";
6
+ //#region src/core/schema/value.d.ts
7
+ /**
8
+ * Which surface handed a raw value to the value layer.
9
+ *
10
+ * `'token'` is a CLI argv token; the rest name the resolver stage that produced
11
+ * the value. Codecs widen what they accept as the input gets further from argv.
12
+ * `'stdin'` accepts exactly what `'env'` accepts: both deliver a raw string a
13
+ * user typed outside argv, so neither gets the extra latitude a prompt answer
14
+ * or a typed config value gets.
15
+ */
16
+ type ValueInput = "token" | "stdin" | "env" | "config" | "prompt";
17
+ /** The primitive a codec could not read a raw value as. */
18
+ type ValueTypeName = "string" | "number" | "boolean";
19
+ /** Why decoding rejected a raw value. */
20
+ type ValueFailure = {
21
+ readonly kind: "type";
22
+ readonly expected: ValueTypeName;
23
+ } | {
24
+ readonly kind: "enum";
25
+ readonly enumValues: readonly string[] | undefined;
26
+ } | {
27
+ readonly kind: "string-constraint";
28
+ readonly value: string;
29
+ readonly violation: StringConstraintViolation;
30
+ } | {
31
+ readonly kind: "number-constraint";
32
+ readonly value: number;
33
+ readonly violation: NumberConstraintViolation;
34
+ } | {
35
+ readonly kind: "thrown";
36
+ readonly error: unknown;
37
+ };
38
+ /** The outcome of decoding one raw value. */
39
+ type ValueResult<T> = {
40
+ readonly ok: true;
41
+ readonly value: T;
42
+ } | {
43
+ readonly ok: false;
44
+ readonly failure: ValueFailure;
45
+ };
46
+ /** Reads one raw value from one input surface into a typed value. */
47
+ type ValueDecoder<T> = (raw: unknown, input: ValueInput) => ValueResult<T>;
48
+ /** The narrowest shape every surface's parse function satisfies. */
49
+ type ValueParseFn = (raw: never) => unknown;
50
+ /** How a raw value becomes a typed one, plus the data the definition round-trip needs. */
51
+ type ValueCodec<T = unknown, P = ValueParseFn> = {
52
+ readonly name: "string";
53
+ readonly decode: ValueDecoder<T>;
54
+ } | {
55
+ readonly name: "number";
56
+ readonly decode: ValueDecoder<T>;
57
+ } | {
58
+ readonly name: "boolean";
59
+ readonly decode: ValueDecoder<T>;
60
+ } | {
61
+ readonly name: "enum";
62
+ readonly enumValues: readonly string[] | undefined;
63
+ readonly decode: ValueDecoder<T>;
64
+ } | {
65
+ readonly name: "custom";
66
+ readonly parseFn: P | undefined;
67
+ readonly decode: ValueDecoder<T>;
68
+ };
69
+ /** Rules a decoded value must satisfy, discriminated by the codec that produced it. */
70
+ type ValueConstraints = {
71
+ readonly kind: "string";
72
+ readonly stringConstraints: StringConstraints | undefined;
73
+ } | {
74
+ readonly kind: "number";
75
+ readonly numberConstraints: NumberConstraints | undefined;
76
+ };
77
+ /** Everything the value axis of a flag or an arg carries. */
78
+ interface ValueSchema<T = unknown, P = ValueParseFn> {
79
+ /** How a raw value becomes a typed one. */
80
+ readonly codec: ValueCodec<T, P>;
81
+ /** Rules the decoded value must satisfy, or `undefined` when the codec has none. */
82
+ readonly constraints: ValueConstraints | undefined;
83
+ /** Standard Schema v1 validator applied to the resolved value. */
84
+ readonly standard: StandardSchemaV1 | undefined;
85
+ /** Filesystem checks applied to the resolved value. */
86
+ readonly pathChecks: PathChecks | undefined;
87
+ /** Help placeholder label (`'url'` renders as `<url>`). */
88
+ readonly valueHint: string | undefined;
89
+ }
90
+ /** The flat definition fields a {@link ValueSchema} contributes to a flag or arg definition. */
91
+ interface ValueDefinitionFields<P = ValueParseFn> {
92
+ /** String constraints, when the codec is `'string'` and any were declared. */
93
+ readonly stringConstraints?: StringConstraints;
94
+ /** Numeric constraints, when the codec is `'number'` and any were declared. */
95
+ readonly numberConstraints?: NumberConstraints;
96
+ /** Parse function, when the codec is `'custom'` and one was supplied. */
97
+ readonly parseFn?: P;
98
+ /** Standard Schema v1 validator, when one was supplied. */
99
+ readonly standard?: StandardSchemaV1;
100
+ /** Filesystem checks, when any were declared. */
101
+ readonly pathChecks?: PathChecks;
102
+ /** Help placeholder label, when the factory set one. */
103
+ readonly valueHint?: string;
104
+ }
105
+ /**
106
+ * Decode a raw value and apply the constraints riding on the value schema.
107
+ *
108
+ * The single entry point both the parse boundary and the resolver coercion
109
+ * boundary use, so the two cannot drift on what a value means.
110
+ *
111
+ * @param value - The value axis of the flag or arg receiving the raw value.
112
+ * @param raw - The raw token, env string, config value, or prompt answer.
113
+ * @param input - Which surface produced `raw`.
114
+ * @returns The decoded value, or the {@link ValueFailure} that rejected it.
115
+ */
116
+ declare function decodeValue(value: ValueSchema, raw: unknown, input: ValueInput): ValueResult<unknown>;
117
+ /**
118
+ * Drop the line terminator a pipe appends.
119
+ *
120
+ * @param text - The raw stdin buffer.
121
+ * @returns The text without its single trailing terminator.
122
+ */
123
+ declare function stripTerminator(text: string): string;
124
+ /**
125
+ * Whether decoding leaves the line terminator a pipe appends on the value.
126
+ *
127
+ * @param value - The value axis about to read a stdin buffer.
128
+ * @returns `true` when the terminator survives decoding.
129
+ */
130
+ declare function keepsStdinTerminator(value: ValueSchema): boolean;
131
+ /**
132
+ * Check a value that skipped decoding against everything the codec would have
133
+ * produced and the constraints would have enforced.
134
+ *
135
+ * A declared default is already the typed value, so it is validated rather than
136
+ * read from a raw source: it must lie in the codec's own output domain, and it
137
+ * must satisfy the constraints. Standard Schema and filesystem checks ride on
138
+ * the value schema separately and stay with their own passes.
139
+ *
140
+ * @param value - The value axis declaring the codec and the constraints.
141
+ * @param decoded - The already-typed value to check.
142
+ * @returns The {@link ValueFailure} that rejected it, or `undefined` when it passes.
143
+ */
144
+ declare function validateDecodedValue(value: ValueSchema, decoded: unknown): ValueFailure | undefined;
145
+ /**
146
+ * Describe a value failure in the words a message can carry.
147
+ *
148
+ * The subject the value belonged to is the caller's to name.
149
+ *
150
+ * @param failure - What the value layer rejected.
151
+ * @returns One clause stating the problem.
152
+ */
153
+ declare function describeValueFailure(failure: ValueFailure): string;
154
+ /** A string value, optionally constrained. */
155
+ declare function stringValue(stringConstraints?: StringConstraints): ValueSchema<string>;
156
+ /**
157
+ * A string value that accepts nothing but a string, from every input.
158
+ *
159
+ * The implicit element of an entries collection, whose values are strings on
160
+ * every source rather than a config scalar a string codec would stringify.
161
+ */
162
+ declare function strictStringValue(): ValueSchema<string>;
163
+ /** A number value, optionally constrained. Finiteness applies with or without constraints. */
164
+ declare function numberValue(numberConstraints?: NumberConstraints): ValueSchema<number>;
165
+ /** A boolean value. */
166
+ declare function booleanValue(): ValueSchema<boolean>;
167
+ /** A value restricted to the declared literals. */
168
+ declare function enumValue(enumValues: readonly string[] | undefined): ValueSchema<string>;
169
+ /** A value produced by a flag-style parse function, which accepts any raw source value. */
170
+ declare function customValue<P extends (raw: unknown) => unknown>(parseFn: P): ValueSchema<unknown, P>;
171
+ /** A value produced by an arg-style parse function, which only ever receives strings. */
172
+ declare function stringParsedValue<P extends (raw: string) => unknown>(parseFn: P): ValueSchema<unknown, P>;
173
+ /** A value validated by a Standard Schema v1 validator instead of a parse function. */
174
+ declare function standardValue(standard: StandardSchemaV1): ValueSchema<unknown, never>;
175
+ /** A value passed through untouched. */
176
+ declare function passthroughValue(): ValueSchema<unknown, never>;
177
+ /** A `URL` value, optionally restricted to an allowlist of protocols. */
178
+ declare function urlValue(options?: UrlFlagOptions): ValueSchema<unknown, (raw: unknown) => URL>;
179
+ /** A path string, with the filesystem checks the options ask for. */
180
+ declare function pathValue(options?: PathFlagOptions): ValueSchema<string>;
181
+ /** A `Date` value parsed from strict ISO-8601, optionally bounded. */
182
+ declare function dateValue(options?: DateFlagOptions): ValueSchema<unknown, (raw: unknown) => Date>;
183
+ /** A duration in milliseconds. */
184
+ declare function durationValue(): ValueSchema<unknown, (raw: unknown) => number>;
185
+ /** A size in bytes. */
186
+ declare function bytesValue(): ValueSchema<unknown, (raw: unknown) => number>;
187
+ /**
188
+ * Flatten a value schema into the definition fields a factory passes to
189
+ * `createFlagSchema()` / `createArgSchema()`.
190
+ *
191
+ * `enumValues` is not among them. Both enum definitions declare that field as
192
+ * required, which an all-optional record cannot satisfy, so the enum factories
193
+ * pass it directly.
194
+ *
195
+ * @param value - The value axis to flatten.
196
+ * @returns Only the fields the value actually declares.
197
+ */
198
+ declare function valueDefinitionFields<T, P>(value: ValueSchema<T, P>): ValueDefinitionFields<P>;
199
+ /**
200
+ * Project a flag schema onto its value axis.
201
+ *
202
+ * A collection projects onto the value of each ELEMENT, so `flag.array()` and
203
+ * `flag.keyValue()` read their element schema's codec, constraints, validator,
204
+ * and path checks here. What the completed collection must satisfy lives on the
205
+ * cardinality axis and is read through {@link flagAggregateStandard}.
206
+ *
207
+ * @param schema - The flag schema to read.
208
+ * @returns The value axis of one value of the flag.
209
+ */
210
+ declare function flagValueSchema(schema: FlagSchema): ValueSchema;
211
+ /**
212
+ * Standard Schema validator applied to a flag's completed collection.
213
+ *
214
+ * @param schema - The flag schema to read.
215
+ * @returns The aggregate validator, or `undefined` for a scalar flag, whose
216
+ * validator is the element's.
217
+ */
218
+ declare function flagAggregateStandard(schema: FlagSchema): StandardSchemaV1 | undefined;
219
+ /**
220
+ * Project an arg schema onto its value axis.
221
+ *
222
+ * An entries arg projects onto the value of each ENTRY, so
223
+ * `arg.keyValue(arg.number())` reads its element schema's codec, constraints,
224
+ * validator, and path checks here. What the completed record must satisfy lives
225
+ * on the cardinality axis and is read through {@link argAggregateStandard}.
226
+ *
227
+ * @param schema - The arg schema to read.
228
+ * @returns The value axis of one value of the arg.
229
+ */
230
+ declare function argValueSchema(schema: ArgSchema): ValueSchema;
231
+ /**
232
+ * Standard Schema validator applied to an arg's completed collection.
233
+ *
234
+ * @param schema - The arg schema to read.
235
+ * @returns The aggregate validator, or `undefined` when none was declared on
236
+ * the collection itself.
237
+ */
238
+ declare function argAggregateStandard(schema: ArgSchema): StandardSchemaV1 | undefined;
239
+ /** The literals an enum value allows, or `undefined` for every other codec. */
240
+ declare function valueEnumValues(value: ValueSchema | undefined): readonly string[] | undefined;
241
+ //#endregion
242
+ export { type ValueCodec, type ValueConstraints, type ValueDecoder, type ValueDefinitionFields, type ValueFailure, type ValueInput, type ValueParseFn, type ValueResult, type ValueSchema, type ValueTypeName, argAggregateStandard, argValueSchema, booleanValue, bytesValue, customValue, dateValue, decodeValue, describeValueFailure, durationValue, enumValue, flagAggregateStandard, flagValueSchema, keepsStdinTerminator, numberValue, passthroughValue, pathValue, standardValue, strictStringValue, stringParsedValue, stringValue, stripTerminator, urlValue, validateDecodedValue, valueDefinitionFields, valueEnumValues };