@kjanat/dreamcli 3.0.1 → 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 (137) hide show
  1. package/CHANGELOG.md +951 -1
  2. package/README.md +7 -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 +9 -9
  134. package/skills/cli-creation/SKILL.md +72 -16
  135. package/skills/cli-creation/references/pattern-cookbook.md +169 -11
  136. package/dist/core/resolve/property.d.mts +0 -51
  137. package/dist/core/resolve/property.mjs +0 -53
@@ -1,4 +1,7 @@
1
1
  import { ValidationError } from "../errors/index.mjs";
2
+ import { argAggregateStandard, argValueSchema, flagAggregateStandard, flagValueSchema } from "../schema/value.mjs";
3
+ import { argCardinality, flagCardinality, isCollection } from "../schema/cardinality.mjs";
4
+ import { echoesValue } from "./redaction.mjs";
2
5
  //#region src/core/resolve/standard.ts
3
6
  /**
4
7
  * Standard Schema v1 validation pass.
@@ -26,15 +29,41 @@ function issuesMessage(label, issues) {
26
29
  return path === void 0 ? issue.message : `${path}: ${issue.message}`;
27
30
  }).join("; ")}`;
28
31
  }
32
+ /**
33
+ * Read one input's provenance by name.
34
+ *
35
+ * @param record - Provenance of one surface, keyed by input name.
36
+ * @param name - Flag or arg name to read.
37
+ * @returns The record, or `undefined` when that input resolved nothing.
38
+ */
39
+ function provenanceOf(record, name) {
40
+ return Object.hasOwn(record, name) ? record[name] : void 0;
41
+ }
29
42
  /** Await a validator against a single value, mapping failure to a typed error. */
30
- async function validateValue(label, value, validator) {
31
- const result = await validator["~standard"].validate(value);
43
+ async function validateValue(label, value, validator, echo) {
44
+ let result;
45
+ try {
46
+ result = await validator["~standard"].validate(value);
47
+ } catch (cause) {
48
+ const message = cause instanceof Error ? cause.message : String(cause);
49
+ return {
50
+ ok: false,
51
+ error: new ValidationError(`${label} validator threw: ${message}`, {
52
+ code: "CONSTRAINT_VIOLATED",
53
+ details: {
54
+ value,
55
+ cause: message
56
+ },
57
+ suggest: `Fix the validator for ${label}, or provide a value it can process`
58
+ })
59
+ };
60
+ }
32
61
  if (result.issues !== void 0) return {
33
62
  ok: false,
34
63
  error: new ValidationError(issuesMessage(label, result.issues), {
35
64
  code: "CONSTRAINT_VIOLATED",
36
65
  details: {
37
- value,
66
+ ...echo ? { value } : {},
38
67
  issues: result.issues.map((issue) => issue.message)
39
68
  },
40
69
  suggest: `Provide a value for ${label} that satisfies its validator`
@@ -46,6 +75,20 @@ async function validateValue(label, value, validator) {
46
75
  };
47
76
  }
48
77
  /**
78
+ * Read one resolved value by name.
79
+ *
80
+ * `resolve()` runs this pass even after a resolver threw, so the record may be
81
+ * missing a declared name, and a name such as `toString` reads back the
82
+ * inherited `Object.prototype` method from a bare lookup.
83
+ *
84
+ * @param values - Resolved flag or arg record.
85
+ * @param name - Flag or arg name to read.
86
+ * @returns The resolved value, or `undefined` when the record does not carry it.
87
+ */
88
+ function resolvedValue(values, name) {
89
+ return Object.hasOwn(values, name) ? values[name] : void 0;
90
+ }
91
+ /**
49
92
  * Validate resolved flag and arg values against any attached Standard Schema
50
93
  * validators. Values without a validator, or resolved to `undefined`, pass
51
94
  * through untouched.
@@ -53,56 +96,25 @@ async function validateValue(label, value, validator) {
53
96
  * @param schema - The command schema carrying per-flag/arg validators.
54
97
  * @param flags - Resolved flag values, keyed by flag name.
55
98
  * @param args - Resolved arg values, keyed by arg name.
99
+ * @param provenance - Which stage produced each value, read for redaction.
56
100
  * @returns The (possibly transformed) values and any constraint violations.
57
101
  * @internal
58
102
  */
59
- async function applyStandardValidators(schema, flags, args) {
103
+ async function applyStandardValidators(schema, flags, args, provenance) {
60
104
  const errors = [];
61
105
  const nextFlags = { ...flags };
62
106
  for (const [name, flagSchema] of Object.entries(schema.flags)) {
63
- const value = flags[name];
107
+ const value = resolvedValue(flags, name);
64
108
  if (value === void 0) continue;
65
- const elementValidator = flagSchema.kind === "array" ? flagSchema.elementSchema?.standard : void 0;
66
- if (elementValidator !== void 0 && Array.isArray(value)) {
67
- const nextValue = [];
68
- for (const [index, element] of value.entries()) {
69
- const result = await validateValue(`--${name}[${index}]`, element, elementValidator);
70
- if (result.ok) nextValue.push(result.value);
71
- else {
72
- nextValue.push(element);
73
- errors.push(result.error);
74
- }
75
- }
76
- nextFlags[name] = nextValue;
77
- continue;
78
- }
79
- const validator = flagSchema.standard;
80
- if (validator === void 0) continue;
81
- const result = await validateValue(`--${name}`, value, validator);
82
- if (result.ok) nextFlags[name] = result.value;
83
- else errors.push(result.error);
109
+ const validated = await validateInput(`--${name}`, value, isCollection(flagCardinality(flagSchema)), flagValueSchema(flagSchema).standard, flagAggregateStandard(flagSchema), errors, echoesValue(provenanceOf(provenance.flags, name)));
110
+ if (validated.changed) nextFlags[name] = validated.value;
84
111
  }
85
112
  const nextArgs = { ...args };
86
113
  for (const entry of schema.args) {
87
- const validator = entry.schema.standard;
88
- const value = args[entry.name];
89
- if (validator === void 0 || value === void 0) continue;
90
- if (entry.schema.variadic && Array.isArray(value)) {
91
- const nextValue = [];
92
- for (const [index, element] of value.entries()) {
93
- const result = await validateValue(`<${entry.name}>[${index}]`, element, validator);
94
- if (result.ok) nextValue.push(result.value);
95
- else {
96
- nextValue.push(element);
97
- errors.push(result.error);
98
- }
99
- }
100
- nextArgs[entry.name] = nextValue;
101
- continue;
102
- }
103
- const result = await validateValue(`<${entry.name}>`, value, validator);
104
- if (result.ok) nextArgs[entry.name] = result.value;
105
- else errors.push(result.error);
114
+ const value = resolvedValue(args, entry.name);
115
+ if (value === void 0) continue;
116
+ const validated = await validateInput(`<${entry.name}>`, value, isCollection(argCardinality(entry.schema)), argValueSchema(entry.schema).standard, argAggregateStandard(entry.schema), errors, echoesValue(provenanceOf(provenance.args, entry.name)));
117
+ if (validated.changed) nextArgs[entry.name] = validated.value;
106
118
  }
107
119
  return {
108
120
  flags: nextFlags,
@@ -110,5 +122,91 @@ async function applyStandardValidators(schema, flags, args) {
110
122
  errors
111
123
  };
112
124
  }
125
+ /**
126
+ * Run the element pass and then the aggregate pass over one resolved value.
127
+ *
128
+ * A collection validates every element before the completed array or record
129
+ * reaches the aggregate validator, so an element issue names the element.
130
+ *
131
+ * @param label - How the input is spelled in diagnostics.
132
+ * @param value - The resolved value.
133
+ * @param collection - Whether the input's cardinality aggregates values.
134
+ * @param element - Validator for each element, or for the value itself.
135
+ * @param aggregate - Validator for the completed collection.
136
+ * @param errors - Collector for the issues found.
137
+ * @param echo - Whether a diagnostic may record the value.
138
+ * @returns The value to store, and whether validation replaced it.
139
+ */
140
+ async function validateInput(label, value, collection, element, aggregate, errors, echo) {
141
+ let current = value;
142
+ let changed = false;
143
+ const errorCount = errors.length;
144
+ if (element !== void 0) {
145
+ const validated = collection ? await validateElements(label, current, element, errors, echo) : await validateOne(label, current, element, errors, echo);
146
+ current = validated.value;
147
+ changed = changed || validated.changed;
148
+ }
149
+ if (aggregate !== void 0 && errors.length === errorCount) {
150
+ const result = await validateValue(label, current, aggregate, echo);
151
+ if (result.ok) {
152
+ current = result.value;
153
+ changed = true;
154
+ } else errors.push(result.error);
155
+ }
156
+ return {
157
+ changed,
158
+ value: current
159
+ };
160
+ }
161
+ /** Apply the element validator to a value, entry by entry when it is a collection. */
162
+ async function validateElements(label, value, validator, errors, echo) {
163
+ if (Array.isArray(value)) {
164
+ const next = [];
165
+ for (const [index, element] of value.entries()) {
166
+ const result = await validateValue(`${label}[${index}]`, element, validator, echo);
167
+ if (result.ok) next.push(result.value);
168
+ else {
169
+ next.push(element);
170
+ errors.push(result.error);
171
+ }
172
+ }
173
+ return {
174
+ changed: true,
175
+ value: next
176
+ };
177
+ }
178
+ if (isPlainRecord(value)) {
179
+ const next = /* @__PURE__ */ new Map();
180
+ for (const [key, entry] of Object.entries(value)) {
181
+ const result = await validateValue(`${label}.${key}`, entry, validator, echo);
182
+ next.set(key, result.ok ? result.value : entry);
183
+ if (!result.ok) errors.push(result.error);
184
+ }
185
+ return {
186
+ changed: true,
187
+ value: Object.fromEntries(next)
188
+ };
189
+ }
190
+ return validateOne(label, value, validator, errors, echo);
191
+ }
192
+ /** Apply a validator to one value. */
193
+ async function validateOne(label, value, validator, errors, echo) {
194
+ const result = await validateValue(label, value, validator, echo);
195
+ if (result.ok) return {
196
+ changed: true,
197
+ value: result.value
198
+ };
199
+ errors.push(result.error);
200
+ return {
201
+ changed: false,
202
+ value
203
+ };
204
+ }
205
+ /** Whether a resolved value is the record an entries collection produces. */
206
+ function isPlainRecord(value) {
207
+ if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
208
+ const prototype = Object.getPrototypeOf(value);
209
+ return prototype === Object.prototype || prototype === null;
210
+ }
113
211
  //#endregion
114
212
  export { applyStandardValidators };
@@ -15,7 +15,7 @@
15
15
  * - `'static'` — emit plain text via `out.log()` / `out.error()` at
16
16
  * lifecycle boundaries (start, succeed, fail). No animation.
17
17
  */
18
- type Fallback = 'silent' | 'static';
18
+ type Fallback = "silent" | "static";
19
19
  /** Options for {@link Out.spinner}. */
20
20
  interface SpinnerOptions {
21
21
  /**
@@ -88,52 +88,52 @@ interface ProgressHandle {
88
88
  */
89
89
  type ActivityEvent = {
90
90
  /** Spinner created and started. */
91
- readonly type: 'spinner:start';
91
+ readonly type: "spinner:start";
92
92
  /** Initial spinner text. */
93
93
  readonly text: string;
94
94
  } | {
95
95
  /** Spinner text changed. */
96
- readonly type: 'spinner:update';
96
+ readonly type: "spinner:update";
97
97
  /** Updated spinner text. */
98
98
  readonly text: string;
99
99
  } | {
100
100
  /** Spinner completed successfully. */
101
- readonly type: 'spinner:succeed';
101
+ readonly type: "spinner:succeed";
102
102
  /** Success message. */
103
103
  readonly text: string;
104
104
  } | {
105
105
  /** Spinner stopped with an error. */
106
- readonly type: 'spinner:fail';
106
+ readonly type: "spinner:fail";
107
107
  /** Failure message. */
108
108
  readonly text: string;
109
109
  } | {
110
110
  /** Spinner stopped without a final status. */
111
- readonly type: 'spinner:stop';
111
+ readonly type: "spinner:stop";
112
112
  } | {
113
113
  /** Progress bar created and started. */
114
- readonly type: 'progress:start';
114
+ readonly type: "progress:start";
115
115
  /** Bar label. */
116
116
  readonly label: string;
117
117
  /** Known total, or `undefined` for indeterminate. */
118
118
  readonly total: number | undefined;
119
119
  } | {
120
120
  /** Progress bar advanced. */
121
- readonly type: 'progress:increment';
121
+ readonly type: "progress:increment";
122
122
  /** Amount advanced. */
123
123
  readonly delta: number;
124
124
  } | {
125
125
  /** Progress bar set to an absolute value. */
126
- readonly type: 'progress:update';
126
+ readonly type: "progress:update";
127
127
  /** New absolute value. */
128
128
  readonly value: number;
129
129
  } | {
130
130
  /** Progress bar completed. */
131
- readonly type: 'progress:done';
131
+ readonly type: "progress:done";
132
132
  /** Completion message, if any. */
133
133
  readonly text: string | undefined;
134
134
  } | {
135
135
  /** Progress bar stopped with an error. */
136
- readonly type: 'progress:fail';
136
+ readonly type: "progress:fail";
137
137
  /** Failure message, if any. */
138
138
  readonly text: string | undefined;
139
139
  };
@@ -152,9 +152,9 @@ interface TableColumn<T extends Record<string, unknown>> {
152
152
  readonly header?: string;
153
153
  }
154
154
  /** Render format override for {@link Out.table}. */
155
- type TableFormat = 'auto' | 'text' | 'json';
155
+ type TableFormat = "auto" | "text" | "json";
156
156
  /** Output stream override for text table rendering. */
157
- type TableStream = 'stdout' | 'stderr';
157
+ type TableStream = "stdout" | "stderr";
158
158
  /**
159
159
  * Per-call table output options.
160
160
  *
@@ -169,17 +169,17 @@ interface TableOptionsAuto {
169
169
  * Follow the current output mode (text in normal, JSON in jsonMode).
170
170
  * @defaultValue `'auto'`
171
171
  */
172
- readonly format?: 'auto';
172
+ readonly format?: "auto";
173
173
  }
174
174
  /** Force JSON array output to stdout regardless of output mode. */
175
175
  interface TableOptionsJson {
176
176
  /** Always emit a JSON array to stdout. */
177
- readonly format: 'json';
177
+ readonly format: "json";
178
178
  }
179
179
  /** Force human-readable text table output, optionally routed to a specific {@link TableStream}. */
180
180
  interface TableOptionsText {
181
181
  /** Always render a human-readable text table. */
182
- readonly format: 'text';
182
+ readonly format: "text";
183
183
  /** Target stream for text output. Falls back to stdout (stderr in jsonMode). */
184
184
  readonly stream?: TableStream;
185
185
  }