@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.
- package/CHANGELOG.md +967 -1
- package/README.md +9 -3
- package/dist/core/cli/builtins.d.mts +47 -0
- package/dist/core/cli/builtins.mjs +135 -0
- package/dist/core/cli/compiled.d.mts +29 -0
- package/dist/core/cli/compiled.mjs +76 -0
- package/dist/core/cli/dispatch.d.mts +9 -85
- package/dist/core/cli/help-links.d.mts +2 -14
- package/dist/core/cli/index.d.mts +282 -101
- package/dist/core/cli/index.mjs +497 -264
- package/dist/core/cli/planner.d.mts +13 -86
- package/dist/core/cli/planner.mjs +47 -30
- package/dist/core/cli/plugin.d.mts +1 -1
- package/dist/core/cli/propagate.mjs +1 -1
- package/dist/core/cli/reserved-flags.d.mts +1 -0
- package/dist/core/cli/reserved-flags.mjs +158 -0
- package/dist/core/cli/root-help.d.mts +1 -47
- package/dist/core/cli/root-help.mjs +37 -47
- package/dist/core/cli/root-output-flags.d.mts +1 -0
- package/dist/core/cli/root-output-flags.mjs +169 -0
- package/dist/core/cli/root-surface.d.mts +1 -68
- package/dist/core/cli/root-surface.mjs +2 -2
- package/dist/core/cli/runtime-preflight.d.mts +1 -199
- package/dist/core/cli/runtime-preflight.mjs +67 -17
- package/dist/core/completion/index.d.mts +2 -2
- package/dist/core/completion/shells/bash.d.mts +0 -1
- package/dist/core/completion/shells/bash.mjs +2 -1
- package/dist/core/completion/shells/fish.d.mts +0 -1
- package/dist/core/completion/shells/fish.mjs +2 -1
- package/dist/core/completion/shells/powershell.d.mts +0 -1
- package/dist/core/completion/shells/powershell.mjs +2 -1
- package/dist/core/completion/shells/shared.d.mts +3 -114
- package/dist/core/completion/shells/shared.mjs +9 -39
- package/dist/core/completion/shells/zsh.d.mts +0 -1
- package/dist/core/completion/shells/zsh.mjs +2 -1
- package/dist/core/config/index.d.mts +3 -3
- package/dist/core/config/index.mjs +2 -2
- package/dist/core/config/package-json.d.mts +2 -33
- package/dist/core/config/package-json.mjs +1 -34
- package/dist/core/errors/index.d.mts +7 -7
- package/dist/core/execution/index.d.mts +1 -48
- package/dist/core/execution/index.mjs +42 -27
- package/dist/core/help/ansi.d.mts +0 -11
- package/dist/core/help/index.d.mts +3 -35
- package/dist/core/help/index.mjs +29 -6
- package/dist/core/help/theme.d.mts +1 -21
- package/dist/core/json-schema/index.d.mts +279 -10
- package/dist/core/json-schema/index.mjs +482 -237
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +79 -7
- package/dist/core/json-schema/meta-descriptions.generated.mjs +40 -6
- package/dist/core/output/activity.d.mts +1 -193
- package/dist/core/output/activity.mjs +1 -1
- package/dist/core/output/bind.d.mts +1 -37
- package/dist/core/output/contracts.d.mts +7 -13
- package/dist/core/output/contracts.mjs +1 -1
- package/dist/core/output/display-value.d.mts +1 -19
- package/dist/core/output/index.d.mts +5 -187
- package/dist/core/output/index.mjs +44 -9
- package/dist/core/output/renderers.d.mts +1 -45
- package/dist/core/output/writer.d.mts +0 -1
- package/dist/core/parse/index.d.mts +27 -5
- package/dist/core/parse/index.mjs +350 -227
- package/dist/core/parse/occurrences.d.mts +89 -0
- package/dist/core/parse/occurrences.mjs +114 -0
- package/dist/core/prompt/index.d.mts +3 -3
- package/dist/core/read-flags/index.d.mts +150 -0
- package/dist/core/read-flags/index.mjs +217 -0
- package/dist/core/resolve/args.d.mts +35 -4
- package/dist/core/resolve/args.mjs +132 -55
- package/dist/core/resolve/coerce.d.mts +66 -9
- package/dist/core/resolve/coerce.mjs +834 -270
- package/dist/core/resolve/config.d.mts +1 -10
- package/dist/core/resolve/contracts.d.mts +67 -44
- package/dist/core/resolve/errors.mjs +29 -21
- package/dist/core/resolve/flags.d.mts +36 -9
- package/dist/core/resolve/flags.mjs +129 -151
- package/dist/core/resolve/index.d.mts +8 -6
- package/dist/core/resolve/index.mjs +51 -18
- package/dist/core/resolve/path-checks.d.mts +47 -0
- package/dist/core/resolve/path-checks.mjs +102 -0
- package/dist/core/resolve/redaction.d.mts +12 -0
- package/dist/core/resolve/redaction.mjs +14 -0
- package/dist/core/resolve/stages.d.mts +85 -0
- package/dist/core/resolve/stages.mjs +170 -0
- package/dist/core/resolve/standard.d.mts +1 -24
- package/dist/core/resolve/standard.mjs +141 -43
- package/dist/core/schema/activity.d.mts +16 -16
- package/dist/core/schema/arg.d.mts +849 -71
- package/dist/core/schema/arg.mjs +727 -54
- package/dist/core/schema/brand.d.mts +17 -0
- package/dist/core/schema/cardinality.d.mts +301 -0
- package/dist/core/schema/cardinality.mjs +514 -0
- package/dist/core/schema/command.d.mts +181 -112
- package/dist/core/schema/command.mjs +305 -42
- package/dist/core/schema/flag.d.mts +515 -173
- package/dist/core/schema/flag.mjs +576 -78
- package/dist/core/schema/index.d.mts +11 -8
- package/dist/core/schema/index.mjs +10 -0
- package/dist/core/schema/middleware.d.mts +15 -12
- package/dist/core/schema/number-constraints.d.mts +5 -5
- package/dist/core/schema/prompt.d.mts +4 -4
- package/dist/core/schema/provenance.d.mts +99 -0
- package/dist/core/schema/provenance.mjs +28 -0
- package/dist/core/schema/run.d.mts +21 -60
- package/dist/core/schema/source.d.mts +179 -0
- package/dist/core/schema/source.mjs +206 -0
- package/dist/core/schema/standard.d.mts +12 -19
- package/dist/core/schema/stdin.d.mts +87 -0
- package/dist/core/schema/stdin.mjs +91 -0
- package/dist/core/schema/string-constraints.d.mts +16 -5
- package/dist/core/schema/string-constraints.mjs +18 -1
- package/dist/core/schema/value-parsers.d.mts +81 -9
- package/dist/core/schema/value-parsers.mjs +19 -1
- package/dist/core/schema/value.d.mts +242 -0
- package/dist/core/schema/value.mjs +573 -0
- package/dist/core/testkit/index.d.mts +28 -3
- package/dist/core/testkit/index.mjs +40 -26
- package/dist/index.d.mts +21 -16
- package/dist/index.mjs +10 -6
- package/dist/runtime/adapter.d.mts +3 -3
- package/dist/runtime/deno.d.mts +3 -3
- package/dist/runtime/detect.d.mts +2 -2
- package/dist/runtime/node.d.mts +3 -3
- package/dist/runtime/paths.d.mts +1 -31
- package/dist/runtime.d.mts +4 -4
- package/dist/strings.d.mts +1 -16
- package/dist/testkit.d.mts +2 -2
- package/dist/testkit.mjs +1 -1
- package/dist/version.d.mts +0 -13
- package/dist/version.mjs +2 -2
- package/dreamcli.schema.json +368 -78
- package/examples/interactive.ts +6 -5
- package/package.json +10 -9
- package/skills/cli-creation/SKILL.md +196 -0
- package/skills/cli-creation/agents/openai.yaml +4 -0
- package/skills/cli-creation/assets/templates/multi-command.bun-test.ts.tpl +20 -0
- package/skills/cli-creation/assets/templates/multi-command.test.ts.tpl +20 -0
- package/skills/cli-creation/assets/templates/multi-command.ts.tpl +89 -0
- package/skills/cli-creation/assets/templates/single-command.bun-test.ts.tpl +29 -0
- package/skills/cli-creation/assets/templates/single-command.test.ts.tpl +29 -0
- package/skills/cli-creation/assets/templates/single-command.ts.tpl +47 -0
- package/skills/cli-creation/references/consumer-workflow.md +65 -0
- package/skills/cli-creation/references/pattern-cookbook.md +451 -0
- package/skills/cli-creation/references/runtime-notes.md +29 -0
- package/skills/cli-creation/scripts/scaffold_cli.py +360 -0
- package/dist/core/resolve/property.d.mts +0 -51
- package/dist/core/resolve/property.mjs +0 -53
|
@@ -1,9 +1,7 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import {
|
|
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 {
|
|
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,
|
|
158
|
+
declare function createCaptureOutput(options?: Omit<OutputOptions, "stdout" | "stderr">): [out: Out, captured: CapturedOutput];
|
|
341
159
|
//#endregion
|
|
342
|
-
export {
|
|
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
|
-
|
|
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
|
-
|
|
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 (
|
|
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
|
|
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 (
|
|
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
|
|
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
|
|
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
|
|
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,
|
|
512
|
+
export { CaptureOutputChannel, OutputChannel, clearRequestedExitCode, createCaptureOutput, createOutput, getRequestedExitCode, resolveHyperlinkOverride, setRequestedExitCode, writeLine };
|
|
@@ -1,45 +1 @@
|
|
|
1
|
-
|
|
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 {}
|
|
@@ -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:
|
|
12
|
+
readonly kind: "long-flag";
|
|
13
13
|
readonly name: string;
|
|
14
14
|
readonly value: string | undefined;
|
|
15
15
|
} | {
|
|
16
|
-
readonly kind:
|
|
16
|
+
readonly kind: "short-flags";
|
|
17
17
|
readonly chars: string;
|
|
18
18
|
} | {
|
|
19
|
-
readonly kind:
|
|
19
|
+
readonly kind: "positional";
|
|
20
20
|
readonly value: string;
|
|
21
21
|
} | {
|
|
22
|
-
readonly kind:
|
|
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 };
|