@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
@@ -1,9 +1,7 @@
1
- import { ActivityEvent, ProgressHandle, ProgressOptions, SpinnerHandle, SpinnerOptions, TableColumn, TableOptions } from "../schema/activity.mjs";
2
- import { WriteFn, writeLine } from "./writer.mjs";
3
- import { CaptureProgressHandle, CaptureSpinnerHandle, StaticProgressHandle, StaticSpinnerHandle, TTYProgressHandle, TTYSpinnerHandle, noopProgressHandle, noopSpinnerHandle } from "./activity.mjs";
4
- import { OutputPolicy, Verbosity } from "./contracts.mjs";
1
+ import { Verbosity } from "./contracts.mjs";
2
+ import { ActivityEvent } from "../schema/activity.mjs";
5
3
  import { Out } from "../schema/command.mjs";
6
- import { Colors } from "ansispeck";
4
+ import { WriteFn, writeLine } from "./writer.mjs";
7
5
  //#region src/core/output/index.d.ts
8
6
  /**
9
7
  * Configuration for creating an output channel.
@@ -69,22 +67,6 @@ interface OutputOptions {
69
67
  */
70
68
  readonly hyperlinks?: boolean;
71
69
  }
72
- /** Fully resolved output options with no optional fields. */
73
- interface ResolvedOutputOptions {
74
- readonly stdout: WriteFn;
75
- readonly stderr: WriteFn;
76
- readonly isTTY: boolean;
77
- readonly verbosity: Verbosity;
78
- readonly jsonMode: boolean;
79
- readonly color: boolean;
80
- readonly isHyperlinkSupported: boolean;
81
- }
82
- /** Store the exit code requested through an output channel. @internal */
83
- declare function setRequestedExitCode(out: Out, code: number): void;
84
- /** Read the exit code requested through an output channel. @internal */
85
- declare function getRequestedExitCode(out: Out): number | undefined;
86
- /** Clear a previously requested exit code from an output channel. @internal */
87
- declare function clearRequestedExitCode(out: Out): void;
88
70
  /**
89
71
  * Forced hyperlink decision from `NO_HYPERLINKS`/`FORCE_HYPERLINKS` and the
90
72
  * `--no-hyperlinks`/`--hyperlinks` argv flags; `undefined` when unset.
@@ -95,170 +77,6 @@ declare function clearRequestedExitCode(out: Out): void;
95
77
  * @see https://no-hyperlinks.org/
96
78
  */
97
79
  declare function resolveHyperlinkOverride(env: Readonly<Record<string, string | undefined>>, argv: readonly string[]): boolean | undefined;
98
- /**
99
- * Concrete implementation of the {@linkcode Out} interface.
100
- *
101
- * Routes messages to the appropriate writer (stdout vs stderr) and
102
- * respects the configured verbosity level.
103
- *
104
- * Handlers interact with this via the {@linkcode Out} interface — they never see
105
- * {@linkcode OutputChannel} directly, which keeps the coupling minimal.
106
- * Prefer {@link createOutput} unless you are extending the output layer.
107
- *
108
- * @internal
109
- */
110
- declare class OutputChannel implements Out {
111
- /** @internal Resolved configuration. */
112
- readonly options: ResolvedOutputOptions;
113
- /** Semantic output policy snapshot shared by routing helpers. */
114
- readonly policy: OutputPolicy;
115
- /** Whether JSON output mode is active. */
116
- readonly jsonMode: boolean;
117
- /**
118
- * Whether stdout is connected to a TTY.
119
- *
120
- * When `jsonMode` is active, this reflects the underlying TTY status
121
- * but decorative output should still be suppressed (jsonMode takes
122
- * precedence).
123
- */
124
- readonly isTTY: boolean;
125
- /**
126
- * Context-aware ANSI color palette.
127
- *
128
- * Enabled per the resolved `color` option — identity functions when
129
- * colors are off, so handlers can style unconditionally.
130
- */
131
- readonly color: Colors;
132
- /**
133
- * Whether OSC 8 hyperlinks should be emitted for this channel.
134
- *
135
- * Honors `NO_HYPERLINKS`/`FORCE_HYPERLINKS` and the
136
- * `--no-hyperlinks`/`--hyperlinks` argv flags, falling back to `isTTY`.
137
- */
138
- readonly isHyperlinkSupported: boolean;
139
- constructor(options: ResolvedOutputOptions);
140
- /**
141
- * Write to stdout (normal output). Always emitted.
142
- *
143
- * In JSON mode, redirected to stderr so stdout is reserved for
144
- * structured `json()` output only.
145
- */
146
- log(message: string): void;
147
- /**
148
- * Informational message to stdout.
149
- * Suppressed when verbosity is `'quiet'`.
150
- *
151
- * In JSON mode, redirected to stderr.
152
- */
153
- info(message: string): void;
154
- /**
155
- * Status line to stderr (stdout stays clean for piping).
156
- * Suppressed when verbosity is `'quiet'`.
157
- */
158
- status(message: string): void;
159
- /** Warning to stderr. Always emitted. */
160
- warn(message: string): void;
161
- /** Error to stderr. Always emitted. */
162
- error(message: string): void;
163
- /** Request a successful-process exit code without writing error output. */
164
- setExitCode(code: number): void;
165
- /**
166
- * Emit a structured JSON value to stdout.
167
- *
168
- * Serialises `value` with `JSON.stringify` and writes to stdout
169
- * regardless of JSON mode — `json()` always targets stdout.
170
- */
171
- json(value: unknown): void;
172
- /**
173
- * Render tabular data.
174
- *
175
- * Default behavior matches the current output mode:
176
- * - normal mode → text table to stdout
177
- * - jsonMode → JSON array to stdout
178
- *
179
- * Per-call options can force text/json rendering and route text tables to
180
- * stdout or stderr.
181
- */
182
- table<T extends Record<string, unknown>>(rows: readonly T[], options: TableOptions): void;
183
- table<T extends Record<string, unknown>>(rows: readonly T[], columns?: readonly TableColumn<T>[], options?: TableOptions): void;
184
- /**
185
- * Cleanup callback for the currently active spinner/progress handle.
186
- *
187
- * Set to `undefined` when no handle is active. The callback calls the
188
- * appropriate terminal method (`.stop()` for spinners, `.done()` for
189
- * progress) on the previous handle.
190
- *
191
- * @internal
192
- */
193
- private activeCleanup;
194
- /**
195
- * Stop the currently active spinner/progress handle (if any).
196
- *
197
- * Called internally before creating a new handle to prevent overlap,
198
- * and externally after handler execution to clean up leaked timers.
199
- * Idempotent (safe to call when no handle is active).
200
- */
201
- stopActive(): void;
202
- /**
203
- * Create a spinner handle.
204
- *
205
- * Mode dispatch:
206
- * - `jsonMode` → noop (structured output only, spinners suppressed)
207
- * - `isTTY` → animated TTY spinner (braille frames, ANSI overwrite)
208
- * - `!isTTY && fallback: 'static'` → plain text at lifecycle boundaries
209
- * - `!isTTY && fallback: 'silent'` (default) → noop
210
- *
211
- * All activity output (transient frames, terminal messages) routes to
212
- * stderr so stdout remains clean for structured data and piping.
213
- *
214
- * If another spinner or progress handle is active, it is implicitly
215
- * stopped before the new one starts.
216
- *
217
- * @virtual
218
- */
219
- spinner(text: string, options?: SpinnerOptions): SpinnerHandle;
220
- /**
221
- * Create a progress handle.
222
- *
223
- * Mode dispatch:
224
- * - `jsonMode` → noop (structured output only, progress suppressed)
225
- * - `isTTY` → animated TTY progress bar (determinate or indeterminate)
226
- * - `!isTTY && fallback: 'static'` → plain text at lifecycle boundaries
227
- * - `!isTTY && fallback: 'silent'` (default) → noop
228
- *
229
- * All activity output (transient frames, terminal messages) routes to
230
- * stderr so stdout remains clean for structured data and piping.
231
- *
232
- * If another spinner or progress handle is active, it is implicitly
233
- * stopped before the new one starts.
234
- *
235
- * @virtual
236
- */
237
- progress(opts: ProgressOptions): ProgressHandle;
238
- }
239
- /**
240
- * Output channel variant that returns capture handles for spinner/progress.
241
- *
242
- * Extends {@linkcode OutputChannel} to override `spinner()` and `progress()`, routing
243
- * activity events into a shared {@linkcode ActivityEvent | ActivityEvent[]} for testkit assertion.
244
- * Text output (log/info/warn/error) is handled by the parent class.
245
- *
246
- * @internal
247
- */
248
- declare class CaptureOutputChannel extends OutputChannel {
249
- private readonly activity;
250
- constructor(options: ResolvedOutputOptions, activity: ActivityEvent[]);
251
- /**
252
- * Return a {@link CaptureSpinnerHandle} that records events into the activity log.
253
- * @override
254
- */
255
- spinner(text: string, _options?: SpinnerOptions): SpinnerHandle;
256
- /**
257
- * Return a {@link CaptureProgressHandle} that records events into the activity log.
258
- * @override
259
- */
260
- progress(opts: ProgressOptions): ProgressHandle;
261
- }
262
80
  /**
263
81
  * Create an output channel.
264
82
  *
@@ -337,6 +155,6 @@ interface CapturedOutput {
337
155
  * expect(captured.stderr).toEqual(['danger\n']);
338
156
  * ```
339
157
  */
340
- declare function createCaptureOutput(options?: Omit<OutputOptions, 'stdout' | 'stderr'>): [out: Out, captured: CapturedOutput];
158
+ declare function createCaptureOutput(options?: Omit<OutputOptions, "stdout" | "stderr">): [out: Out, captured: CapturedOutput];
341
159
  //#endregion
342
- export { CaptureOutputChannel, CaptureProgressHandle, CaptureSpinnerHandle, type CapturedOutput, OutputChannel, type OutputOptions, StaticProgressHandle, StaticSpinnerHandle, TTYProgressHandle, TTYSpinnerHandle, type Verbosity, type WriteFn, clearRequestedExitCode, createCaptureOutput, createOutput, getRequestedExitCode, noopProgressHandle, noopSpinnerHandle, resolveHyperlinkOverride, setRequestedExitCode, writeLine };
160
+ export { type CapturedOutput, type OutputOptions, type Verbosity, type WriteFn, createCaptureOutput, createOutput, resolveHyperlinkOverride, writeLine };
@@ -1,3 +1,4 @@
1
+ import "../schema/command.mjs";
1
2
  import { formatDisplayValue } from "./display-value.mjs";
2
3
  import { bindMethods } from "./bind.mjs";
3
4
  import { writeLine } from "./writer.mjs";
@@ -88,6 +89,8 @@ var OutputChannel = class {
88
89
  policy;
89
90
  /** Whether JSON output mode is active. */
90
91
  jsonMode;
92
+ /** Active verbosity level for informational output and activity rendering. */
93
+ verbosity;
91
94
  /**
92
95
  * Whether stdout is connected to a TTY.
93
96
  *
@@ -114,6 +117,7 @@ var OutputChannel = class {
114
117
  this.options = options;
115
118
  this.policy = resolveOutputPolicy(options);
116
119
  this.jsonMode = options.jsonMode;
120
+ this.verbosity = this.policy.verbosity;
117
121
  this.isTTY = options.isTTY;
118
122
  this.color = createColors(options.color);
119
123
  this.isHyperlinkSupported = options.isHyperlinkSupported;
@@ -126,7 +130,8 @@ var OutputChannel = class {
126
130
  * structured `json()` output only.
127
131
  */
128
132
  log(message) {
129
- writeLine(resolveWriterForStream(this.options, resolveTextStream(this.policy)), message);
133
+ const writer = resolveWriterForStream(this.options, resolveTextStream(this.policy));
134
+ writeLine(writer, message);
130
135
  }
131
136
  /**
132
137
  * Informational message to stdout.
@@ -136,7 +141,8 @@ var OutputChannel = class {
136
141
  */
137
142
  info(message) {
138
143
  if (!shouldEmitInfo(this.policy)) return;
139
- writeLine(resolveWriterForStream(this.options, resolveTextStream(this.policy)), message);
144
+ const writer = resolveWriterForStream(this.options, resolveTextStream(this.policy));
145
+ writeLine(writer, message);
140
146
  }
141
147
  /**
142
148
  * Status line to stderr (stdout stays clean for piping).
@@ -206,7 +212,7 @@ var OutputChannel = class {
206
212
  * Create a spinner handle.
207
213
  *
208
214
  * Mode dispatch:
209
- * - `jsonMode` → noop (structured output only, spinners suppressed)
215
+ * - quiet or `jsonMode` → noop (informational activity suppressed)
210
216
  * - `isTTY` → animated TTY spinner (braille frames, ANSI overwrite)
211
217
  * - `!isTTY && fallback: 'static'` → plain text at lifecycle boundaries
212
218
  * - `!isTTY && fallback: 'silent'` (default) → noop
@@ -220,7 +226,8 @@ var OutputChannel = class {
220
226
  * @virtual
221
227
  */
222
228
  spinner(text, options) {
223
- const rendered = createSpinnerHandleFromPolicy(resolveSpinnerPolicy(this.policy, options?.fallback ?? "silent"), text, this.options.stderr);
229
+ const policy = resolveSpinnerPolicy(this.policy, options?.fallback ?? "silent");
230
+ const rendered = createSpinnerHandleFromPolicy(policy, text, this.options.stderr);
224
231
  if (rendered.cleanup === void 0) return rendered.handle;
225
232
  this.stopActive();
226
233
  this.activeCleanup = rendered.cleanup;
@@ -230,7 +237,7 @@ var OutputChannel = class {
230
237
  * Create a progress handle.
231
238
  *
232
239
  * Mode dispatch:
233
- * - `jsonMode` → noop (structured output only, progress suppressed)
240
+ * - quiet or `jsonMode` → noop (informational activity suppressed)
234
241
  * - `isTTY` → animated TTY progress bar (determinate or indeterminate)
235
242
  * - `!isTTY && fallback: 'static'` → plain text at lifecycle boundaries
236
243
  * - `!isTTY && fallback: 'silent'` (default) → noop
@@ -244,7 +251,8 @@ var OutputChannel = class {
244
251
  * @virtual
245
252
  */
246
253
  progress(opts) {
247
- const rendered = createProgressHandleFromPolicy(resolveProgressPolicy(this.policy, opts.fallback ?? "silent"), opts, this.options.stderr);
254
+ const policy = resolveProgressPolicy(this.policy, opts.fallback ?? "silent");
255
+ const rendered = createProgressHandleFromPolicy(policy, opts, this.options.stderr);
248
256
  if (rendered.cleanup === void 0) return rendered.handle;
249
257
  this.stopActive();
250
258
  this.activeCleanup = rendered.cleanup;
@@ -327,6 +335,33 @@ function resolveTableArgs(columnsOrOptions, options) {
327
335
  };
328
336
  }
329
337
  /**
338
+ * Find the object along a row's prototype chain that carries a key.
339
+ *
340
+ * @param row - Source data row.
341
+ * @param key - Column key to locate.
342
+ * @returns The owning object, or `null` when nothing in the chain carries it.
343
+ */
344
+ function cellKeyHolder(row, key) {
345
+ for (let holder = row; holder !== null; holder = Object.getPrototypeOf(holder)) if (Object.hasOwn(holder, key)) return holder;
346
+ return null;
347
+ }
348
+ /**
349
+ * Read one cell out of a row.
350
+ *
351
+ * `Object.prototype` answers a lookup for a column key such as `toString` on
352
+ * every row, so a key it alone carries reads as absent. A key held anywhere
353
+ * earlier in the chain is the row's own data, which is where a class getter or
354
+ * an `Object.create(defaults)` fallback lives.
355
+ *
356
+ * @param row - Source data row.
357
+ * @param key - Column key to read.
358
+ * @returns The cell value, or `undefined` when only `Object.prototype` carries the key.
359
+ */
360
+ function cellValue(row, key) {
361
+ const holder = cellKeyHolder(row, key);
362
+ return holder === null || holder === Object.prototype ? void 0 : row[key];
363
+ }
364
+ /**
330
365
  * Keep only the keys listed in `columns`, preserving column order.
331
366
  *
332
367
  * @param rows - Source data rows.
@@ -334,7 +369,7 @@ function resolveTableArgs(columnsOrOptions, options) {
334
369
  * @returns Projected rows containing only the specified keys.
335
370
  */
336
371
  function projectTableRows(rows, columns) {
337
- return rows.map((row) => Object.fromEntries(columns.map((c) => [c.key, row[c.key]])));
372
+ return rows.map((row) => Object.fromEntries(columns.map((c) => [c.key, cellValue(row, c.key)])));
338
373
  }
339
374
  /**
340
375
  * Determine the concrete table format (`'text'` or `'json'`).
@@ -391,7 +426,7 @@ function formatTable(rows, columns) {
391
426
  if (rows.length === 0 || columns.length === 0) return "";
392
427
  const SEPARATOR = " ";
393
428
  const headers = columns.map((c) => c.header ?? c.key);
394
- const cellGrid = rows.map((row) => columns.map((c) => cellToString(row[c.key])));
429
+ const cellGrid = rows.map((row) => columns.map((c) => cellToString(cellValue(row, c.key))));
395
430
  const widths = headers.map((h, i) => {
396
431
  let max = h.length;
397
432
  for (const row of cellGrid) {
@@ -474,4 +509,4 @@ function createCaptureOutput(options) {
474
509
  }), captured.activity), captured];
475
510
  }
476
511
  //#endregion
477
- export { CaptureOutputChannel, CaptureProgressHandle, CaptureSpinnerHandle, OutputChannel, clearRequestedExitCode, createCaptureOutput, createOutput, getRequestedExitCode, resolveHyperlinkOverride, setRequestedExitCode, writeLine };
512
+ export { CaptureOutputChannel, OutputChannel, clearRequestedExitCode, createCaptureOutput, createOutput, getRequestedExitCode, resolveHyperlinkOverride, setRequestedExitCode, writeLine };
@@ -1,45 +1 @@
1
- import { ProgressHandle, ProgressOptions, SpinnerHandle } from "../schema/activity.mjs";
2
- import { WriteFn } from "./writer.mjs";
3
- import { ActivityPolicy, OutputStream } from "./contracts.mjs";
4
- //#region src/core/output/renderers.d.ts
5
- /**
6
- * Paired write functions for the two standard output streams.
7
- *
8
- * @internal
9
- */
10
- interface OutputWriters {
11
- /** Write function targeting standard output. */
12
- readonly stdout: WriteFn;
13
- /** Write function targeting standard error. */
14
- readonly stderr: WriteFn;
15
- }
16
- /**
17
- * Spinner handle paired with its optional teardown function.
18
- *
19
- * @internal
20
- */
21
- interface SpinnerRenderResult {
22
- /** The spinner handle exposed to command handlers. */
23
- readonly handle: SpinnerHandle;
24
- /** Defined only when the mode requires cleanup (TTY or static); `undefined` for noop. */
25
- readonly cleanup: (() => void) | undefined;
26
- }
27
- /**
28
- * Progress handle paired with its optional teardown function.
29
- *
30
- * @internal
31
- */
32
- interface ProgressRenderResult {
33
- /** The progress handle exposed to command handlers. */
34
- readonly handle: ProgressHandle;
35
- /** Defined only when the mode requires cleanup (TTY or static); `undefined` for noop. */
36
- readonly cleanup: (() => void) | undefined;
37
- }
38
- /** Select the concrete {@linkcode WriteFn} for a given stream label. @internal */
39
- declare function resolveWriterForStream(writers: OutputWriters, stream: OutputStream): WriteFn;
40
- /** Create a spinner handle matching the resolved {@linkcode ActivityPolicy} mode. @internal */
41
- declare function createSpinnerHandleFromPolicy(policy: ActivityPolicy, text: string, stderr: WriteFn): SpinnerRenderResult;
42
- /** Create a progress handle matching the resolved {@linkcode ActivityPolicy} mode. @internal */
43
- declare function createProgressHandleFromPolicy(policy: ActivityPolicy, options: ProgressOptions, stderr: WriteFn): ProgressRenderResult;
44
- //#endregion
45
- export { type OutputWriters, type ProgressRenderResult, type SpinnerRenderResult, createProgressHandleFromPolicy, createSpinnerHandleFromPolicy, resolveWriterForStream };
1
+ export {}
@@ -6,7 +6,6 @@
6
6
  * `activity.ts` (handle classes) can import it without a circular dependency.
7
7
  *
8
8
  * @module dreamcli/core/output/writer
9
- * @internal
10
9
  */
11
10
  /**
12
11
  * A function that writes a string somewhere.
@@ -9,17 +9,17 @@ import "../schema/index.mjs";
9
9
  * interprets them against a command schema.
10
10
  */
11
11
  type Token = {
12
- readonly kind: 'long-flag';
12
+ readonly kind: "long-flag";
13
13
  readonly name: string;
14
14
  readonly value: string | undefined;
15
15
  } | {
16
- readonly kind: 'short-flags';
16
+ readonly kind: "short-flags";
17
17
  readonly chars: string;
18
18
  } | {
19
- readonly kind: 'positional';
19
+ readonly kind: "positional";
20
20
  readonly value: string;
21
21
  } | {
22
- readonly kind: 'separator';
22
+ readonly kind: "separator";
23
23
  };
24
24
  /**
25
25
  * Tokenize raw argv into structured tokens.
@@ -58,6 +58,17 @@ declare function tokenize(argv: readonly string[]): readonly Token[];
58
58
  * @returns `true` if `token` occurs before any `--` separator.
59
59
  */
60
60
  declare function includesBeforeSeparator(argv: readonly string[], token: string): boolean;
61
+ /**
62
+ * Whether argv asks for help before the `--` end-of-options separator.
63
+ *
64
+ * Help renders ahead of flag validation everywhere: a command short-circuits to
65
+ * its help text before `parse()` runs, and the root does the same before
66
+ * dispatch, so a malformed flag value never hides the text explaining the flags.
67
+ *
68
+ * @param argv - Raw argument strings.
69
+ * @returns `true` if `--help` or `-h` occurs before any `--` separator.
70
+ */
71
+ declare function requestsHelp(argv: readonly string[]): boolean;
61
72
  /**
62
73
  * Remove every occurrence of `token` that appears before the `--` end-of-options
63
74
  * separator, leaving post-separator literals untouched.
@@ -132,6 +143,17 @@ declare function buildFlagLookup(flags: Readonly<Record<string, FlagSchema>>, op
132
143
  * @returns `true` if the flag expects a value token after it
133
144
  */
134
145
  declare function flagExpectsValue(schema: FlagSchema): boolean;
146
+ /**
147
+ * Coerce one raw CLI token to what the flag's value axis declares.
148
+ *
149
+ * @param flagName - Canonical flag name (for error messages)
150
+ * @param raw - Raw string value from argv
151
+ * @param schema - {@link FlagSchema} declaring the expected kind
152
+ * @param displayName - Spelling the user typed
153
+ * @returns The coerced token: a value, an element, or a `[key, value]` pair
154
+ * @throws ParseError on type mismatch
155
+ */
156
+ declare function coerceFlagValue(flagName: string, raw: string, schema: FlagSchema, displayName?: string): unknown;
135
157
  /**
136
158
  * Parse tokenized argv against a command schema.
137
159
  *
@@ -153,4 +175,4 @@ declare function flagExpectsValue(schema: FlagSchema): boolean;
153
175
  */
154
176
  declare function parse(schema: CommandSchema, argv: readonly string[], options?: ParseOptions): ParseResult;
155
177
  //#endregion
156
- export { type FlagLookupEntry, type ParseOptions, type ParseResult, type Token, buildFlagLookup, camelToKebab, flagExpectsValue, includesBeforeSeparator, kebabToCamel, parse, stripBeforeSeparator, tokenize };
178
+ export { type FlagLookupEntry, type ParseOptions, type ParseResult, type Token, buildFlagLookup, camelToKebab, coerceFlagValue, flagExpectsValue, includesBeforeSeparator, kebabToCamel, parse, requestsHelp, stripBeforeSeparator, tokenize };