@kjanat/dreamcli 4.1.0 → 5.0.0
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/README.md +3 -1
- package/dist/{adapter-YM5QGi3M.d.mts → adapter-DBeedKmD.d.mts} +5 -3
- package/dist/{completion-CUMeOnAz.mjs → completion-Bh-qywmB.mjs} +4 -4
- package/dist/completion.d.mts +1 -11
- package/dist/completion.mjs +1 -1
- package/dist/config-DruA8aFV.mjs +1 -0
- package/dist/config.d.mts +1 -1
- package/dist/config.mjs +1 -1
- package/dist/core-B9YNSJeA.mjs +19 -0
- package/dist/{index-Cap0MA2V.d.mts → index-AIC5Gler.d.mts} +18 -12
- package/dist/{index-BziI2aKc.d.mts → index-BIMjOsR6.d.mts} +316 -53
- package/dist/{index-3l8uj16E.d.mts → index-BidVVmln.d.mts} +51 -11
- package/dist/index-D683D09G.d.mts +129 -0
- package/dist/{index-DWsnGZlx.d.mts → index-DpslpOVV.d.mts} +160 -154
- package/dist/{index-BAj2y70U.d.mts → index-hzYPRc_O.d.mts} +65 -14
- package/dist/{index-Cp9kt2t-.d.mts → index-jq_FJRKt.d.mts} +1 -7
- package/dist/index.d.mts +18 -11
- package/dist/index.mjs +1 -1
- package/dist/json-schema-DF5fXdKQ.mjs +59 -0
- package/dist/json-schema.d.mts +2 -2
- package/dist/json-schema.mjs +1 -1
- package/dist/package-json-fYhxDdWD.mjs +3 -0
- package/dist/prompt.d.mts +32 -5
- package/dist/prompt.mjs +1 -1
- package/dist/runtime.d.mts +2 -2
- package/dist/runtime.mjs +1 -1
- package/dist/session-Crtzt7LY.mjs +1 -0
- package/dist/terminal-DRsRn4sc.mjs +7 -0
- package/dist/test-prompter-BLNGCOA_.mjs +1 -0
- package/dist/testkit.d.mts +5 -7
- package/dist/testkit.mjs +1 -1
- package/dist/version.d.mts +1 -3
- package/dist/version.mjs +1 -1
- package/dreamcli.schema.json +155 -3
- package/package.json +24 -24
- package/skills/cli-creation/SKILL.md +1 -1
- package/skills/cli-creation/scripts/scaffold_cli.py +12 -4
- package/dist/config-CrlScpYX.mjs +0 -1
- package/dist/core-DvXUolc_.mjs +0 -17
- package/dist/json-schema-DRlrz_IV.mjs +0 -52
- package/dist/package-json-BgE9YjjQ.mjs +0 -3
- package/dist/terminal-C8KTXjv5.mjs +0 -6
- package/dist/test-prompter-v__jT2yG.mjs +0 -1
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
import { A as Out,
|
|
1
|
+
import { A as Out, Gn as HelpThemeFactory, I as ResolutionProvenance, K as Verbosity, Kn as ActivityEvent, b as CommandSchema, nr as schemaBrand, o as PromptEngine, sn as PathChecks, y as CommandMeta } from "./index-BIMjOsR6.mjs";
|
|
2
|
+
import { t as CLIError } from "./index-D683D09G.mjs";
|
|
2
3
|
import { Colors } from "ansispeck";
|
|
3
|
-
//#region src/core/cli/builtins.d.ts
|
|
4
4
|
/** A built-in flag a consumer can take over. */
|
|
5
5
|
type BuiltinName = 'help' | 'json' | 'quiet';
|
|
6
6
|
/** Whether the root keeps a built-in or releases it to commands. */
|
|
@@ -44,138 +44,6 @@ interface Builtins {
|
|
|
44
44
|
/** Whether the root owns `--quiet`/`-q`. */
|
|
45
45
|
readonly quiet: BuiltinMode;
|
|
46
46
|
}
|
|
47
|
-
//#endregion
|
|
48
|
-
//#region src/core/errors/index.d.ts
|
|
49
|
-
/**
|
|
50
|
-
* Structured error types for DreamCLI.
|
|
51
|
-
*
|
|
52
|
-
* Base {@linkcode CLIError} carries stable code, exit code, suggestion, and structured
|
|
53
|
-
* details. {@linkcode ParseError} and {@linkcode ValidationError} derive from it with
|
|
54
|
-
* category-appropriate defaults.
|
|
55
|
-
*
|
|
56
|
-
* @module dreamcli/core/errors
|
|
57
|
-
*/
|
|
58
|
-
/** Codes emitted during argv parsing. */
|
|
59
|
-
type ParseErrorCode = 'UNKNOWN_FLAG' | 'UNKNOWN_COMMAND' | 'MISSING_VALUE' | 'INVALID_VALUE' | 'INVALID_SCHEMA' | 'DUPLICATE_FLAG' | 'UNEXPECTED_POSITIONAL';
|
|
60
|
-
/** Codes emitted during post-parse validation / resolution. */
|
|
61
|
-
type ValidationErrorCode = 'REQUIRED_FLAG' | 'REQUIRED_ARG' | 'MISSING_STDIN' | 'INVALID_ENUM' | 'TYPE_MISMATCH' | 'CONSTRAINT_VIOLATED';
|
|
62
|
-
/** Any framework error code (extensible via `string & {}`). */
|
|
63
|
-
type ErrorCode = ParseErrorCode | ValidationErrorCode | (string & {});
|
|
64
|
-
/** Options accepted by the `CLIError` constructor. */
|
|
65
|
-
interface CLIErrorOptions {
|
|
66
|
-
/** Stable machine-readable identifier (e.g. `"UNKNOWN_FLAG"`). */
|
|
67
|
-
readonly code: ErrorCode;
|
|
68
|
-
/**
|
|
69
|
-
* Process exit code.
|
|
70
|
-
* @defaultValue `1`
|
|
71
|
-
*/
|
|
72
|
-
readonly exitCode?: number;
|
|
73
|
-
/** One-liner actionable hint shown to the user. */
|
|
74
|
-
readonly suggest?: string;
|
|
75
|
-
/** Arbitrary structured payload (serialised in `--json` mode). */
|
|
76
|
-
readonly details?: Readonly<Record<string, unknown>>;
|
|
77
|
-
/** Original error, if this wraps another. */
|
|
78
|
-
readonly cause?: unknown;
|
|
79
|
-
}
|
|
80
|
-
/**
|
|
81
|
-
* Base structured error for DreamCLI.
|
|
82
|
-
*
|
|
83
|
-
* Every error surfaced by the framework extends this class, ensuring a
|
|
84
|
-
* consistent shape for rendering (TTY pretty-print, `--json`, test assertions).
|
|
85
|
-
*/
|
|
86
|
-
declare class CLIError extends Error {
|
|
87
|
-
/** Error class name, always `'CLIError'` for the base class. @override */
|
|
88
|
-
readonly name: string;
|
|
89
|
-
/** Stable machine-readable identifier. */
|
|
90
|
-
readonly code: ErrorCode;
|
|
91
|
-
/** Process exit code (defaults to `1`). */
|
|
92
|
-
readonly exitCode: number;
|
|
93
|
-
/** One-liner actionable hint. */
|
|
94
|
-
readonly suggest: string | undefined;
|
|
95
|
-
/** Structured payload for machine output. */
|
|
96
|
-
readonly details: Readonly<Record<string, unknown>> | undefined;
|
|
97
|
-
/** Create a structured CLI error from a human message and machine-readable options. */
|
|
98
|
-
constructor(message: string, options: CLIErrorOptions);
|
|
99
|
-
/**
|
|
100
|
-
* Serialise to a plain object suitable for JSON output.
|
|
101
|
-
*
|
|
102
|
-
* `details` is projected onto JSON-representable values: bigints become
|
|
103
|
-
* decimal digits and entries JSON cannot carry are omitted. The error
|
|
104
|
-
* object itself keeps the runtime values.
|
|
105
|
-
*
|
|
106
|
-
* @sealed
|
|
107
|
-
*/
|
|
108
|
-
toJSON(): CLIErrorJSON;
|
|
109
|
-
}
|
|
110
|
-
/** Shape returned by {@linkcode CLIError}.toJSON(). */
|
|
111
|
-
interface CLIErrorJSON {
|
|
112
|
-
/** Error class name (e.g. `'CLIError'`, `'ParseError'`). */
|
|
113
|
-
readonly name: string;
|
|
114
|
-
/** Stable machine-readable identifier for programmatic matching. */
|
|
115
|
-
readonly code: ErrorCode;
|
|
116
|
-
/** Human-readable description of what went wrong. */
|
|
117
|
-
readonly message: string;
|
|
118
|
-
/** Process exit code associated with this error. */
|
|
119
|
-
readonly exitCode: number;
|
|
120
|
-
/** Actionable hint shown to the user, when available. */
|
|
121
|
-
readonly suggest?: string;
|
|
122
|
-
/** Structured payload for machine consumers, when available. */
|
|
123
|
-
readonly details?: Readonly<Record<string, unknown>>;
|
|
124
|
-
}
|
|
125
|
-
/** Options for {@linkcode ParseError}. Code is narrowed to parse-specific codes. */
|
|
126
|
-
interface ParseErrorOptions extends Omit<CLIErrorOptions, 'code' | 'exitCode'> {
|
|
127
|
-
/** Parse-category error code (e.g. `'UNKNOWN_FLAG'`, `'MISSING_VALUE'`). */
|
|
128
|
-
readonly code: ParseErrorCode;
|
|
129
|
-
/**
|
|
130
|
-
* Process exit code for parse failures.
|
|
131
|
-
* @defaultValue `2`
|
|
132
|
-
*/
|
|
133
|
-
readonly exitCode?: number;
|
|
134
|
-
}
|
|
135
|
-
/**
|
|
136
|
-
* Error thrown when argv tokenization / parsing fails.
|
|
137
|
-
*
|
|
138
|
-
* Exit code defaults to `2` (standard for CLI usage errors).
|
|
139
|
-
*/
|
|
140
|
-
declare class ParseError extends CLIError {
|
|
141
|
-
/** Always `'ParseError'`. @override */
|
|
142
|
-
readonly name: "ParseError";
|
|
143
|
-
/** Narrowed to parse-category codes. */
|
|
144
|
-
readonly code: ParseErrorCode;
|
|
145
|
-
/** Create a parse error with exit code defaulting to `2`. */
|
|
146
|
-
constructor(message: string, options: ParseErrorOptions);
|
|
147
|
-
}
|
|
148
|
-
/** Options for {@linkcode ValidationError}. Code is narrowed to validation-specific codes. */
|
|
149
|
-
interface ValidationErrorOptions extends Omit<CLIErrorOptions, 'code' | 'exitCode'> {
|
|
150
|
-
/** Validation-category error code (e.g. `'REQUIRED_FLAG'`, `'INVALID_ENUM'`). */
|
|
151
|
-
readonly code: ValidationErrorCode;
|
|
152
|
-
/**
|
|
153
|
-
* Process exit code for validation failures.
|
|
154
|
-
* @defaultValue `2`
|
|
155
|
-
*/
|
|
156
|
-
readonly exitCode?: number;
|
|
157
|
-
}
|
|
158
|
-
/**
|
|
159
|
-
* Error thrown when resolved values fail validation constraints.
|
|
160
|
-
*
|
|
161
|
-
* Exit code defaults to `2` (standard for CLI usage errors).
|
|
162
|
-
*/
|
|
163
|
-
declare class ValidationError extends CLIError {
|
|
164
|
-
/** Always `'ValidationError'`. @override */
|
|
165
|
-
readonly name: "ValidationError";
|
|
166
|
-
/** Narrowed to validation-category codes. */
|
|
167
|
-
readonly code: ValidationErrorCode;
|
|
168
|
-
/** Create a validation error with exit code defaulting to `2`. */
|
|
169
|
-
constructor(message: string, options: ValidationErrorOptions);
|
|
170
|
-
}
|
|
171
|
-
/** Narrows an unknown value to `CLIError`. */
|
|
172
|
-
declare function isCLIError(value: unknown): value is CLIError;
|
|
173
|
-
/** Narrows an unknown value to `ParseError`. */
|
|
174
|
-
declare function isParseError(value: unknown): value is ParseError;
|
|
175
|
-
/** Narrows an unknown value to `ValidationError`. */
|
|
176
|
-
declare function isValidationError(value: unknown): value is ValidationError;
|
|
177
|
-
//#endregion
|
|
178
|
-
//#region src/core/parse/index.d.ts
|
|
179
47
|
/**
|
|
180
48
|
* Token discriminated union.
|
|
181
49
|
*
|
|
@@ -289,8 +157,6 @@ interface ParseOptions {
|
|
|
289
157
|
* ```
|
|
290
158
|
*/
|
|
291
159
|
declare function parse(schema: CommandSchema, argv: readonly string[], options?: ParseOptions): ParseResult;
|
|
292
|
-
//#endregion
|
|
293
|
-
//#region src/core/resolve/contracts.d.ts
|
|
294
160
|
/**
|
|
295
161
|
* External state the resolver may consult after parsing.
|
|
296
162
|
*
|
|
@@ -318,6 +184,56 @@ interface ResolveOptions {
|
|
|
318
184
|
* apply as-is.
|
|
319
185
|
*/
|
|
320
186
|
readonly mkdir?: (path: string) => Promise<void>;
|
|
187
|
+
/**
|
|
188
|
+
* What happens to a declared filesystem check that cannot run because
|
|
189
|
+
* {@link ResolveOptions.stat} (or {@link ResolveOptions.mkdir} for `create`)
|
|
190
|
+
* is absent.
|
|
191
|
+
*
|
|
192
|
+
* - `'lenient'` — the check is skipped and recorded in
|
|
193
|
+
* {@link ResolveResult.skippedPathChecks}, so a result can still report
|
|
194
|
+
* that it was never exercised.
|
|
195
|
+
* - `'strict'` — resolution fails with a `CLIError` of code
|
|
196
|
+
* `'PATH_CHECK_SKIPPED'` (exit code `1`) naming every skipped input, for
|
|
197
|
+
* tests that must exercise each declared check.
|
|
198
|
+
*
|
|
199
|
+
* Only inputs that resolved a path value are affected: an unset optional
|
|
200
|
+
* path has nothing to check in production either.
|
|
201
|
+
*
|
|
202
|
+
* @defaultValue `'lenient'`
|
|
203
|
+
*/
|
|
204
|
+
readonly pathChecks?: 'lenient' | 'strict';
|
|
205
|
+
/**
|
|
206
|
+
* Environment namespace prepended to every relative env binding, the count
|
|
207
|
+
* and templates of an indexed family included. A binding declared
|
|
208
|
+
* `absolute` is read as written. Diagnostics and provenance name the
|
|
209
|
+
* concrete variable.
|
|
210
|
+
*
|
|
211
|
+
* @defaultValue `undefined` (no namespace)
|
|
212
|
+
*/
|
|
213
|
+
readonly envPrefix?: string;
|
|
214
|
+
}
|
|
215
|
+
/**
|
|
216
|
+
* A declared `flag.path()` / `arg.path()` check that resolution had no means
|
|
217
|
+
* to run.
|
|
218
|
+
*
|
|
219
|
+
* Recorded instead of raised when {@link ResolveOptions.pathChecks} is
|
|
220
|
+
* `'lenient'` (the default): the value resolved and the handler ran, but the
|
|
221
|
+
* filesystem was never consulted, so a passing result does not prove the real
|
|
222
|
+
* CLI would accept the same path.
|
|
223
|
+
*/
|
|
224
|
+
interface SkippedPathCheck {
|
|
225
|
+
/** Whether the path belongs to a flag or a positional arg. */
|
|
226
|
+
readonly kind: 'flag' | 'arg';
|
|
227
|
+
/** Name of the flag or arg. */
|
|
228
|
+
readonly name: string;
|
|
229
|
+
/** The checks the schema declared (`mustExist`, `type`, `create`). */
|
|
230
|
+
readonly checks: PathChecks;
|
|
231
|
+
/**
|
|
232
|
+
* The capability resolution lacked: `'stat'` when no probe was supplied so
|
|
233
|
+
* no check ran, or `'mkdir'` when the path was missing, `create` was
|
|
234
|
+
* declared, and nothing could create it.
|
|
235
|
+
*/
|
|
236
|
+
readonly missing: 'stat' | 'mkdir';
|
|
321
237
|
}
|
|
322
238
|
/** Structured deprecation notice emitted for explicitly sourced values. */
|
|
323
239
|
interface DeprecationWarning {
|
|
@@ -348,14 +264,18 @@ interface ResolveResult {
|
|
|
348
264
|
readonly args: Readonly<Record<string, unknown>>;
|
|
349
265
|
/** Deprecation notices collected during resolution (may be empty). */
|
|
350
266
|
readonly deprecations: readonly DeprecationWarning[];
|
|
267
|
+
/**
|
|
268
|
+
* Declared filesystem checks that did not run because no `stat` probe (or
|
|
269
|
+
* no `mkdir` for `create`) was supplied. Empty when every declared check
|
|
270
|
+
* ran, or when no resolved value had a check to run.
|
|
271
|
+
*/
|
|
272
|
+
readonly skippedPathChecks: readonly SkippedPathCheck[];
|
|
351
273
|
/**
|
|
352
274
|
* Which stage produced each value. Present only for inputs that resolved a
|
|
353
275
|
* value, so an unset optional input has no entry.
|
|
354
276
|
*/
|
|
355
277
|
readonly provenance: ResolutionProvenanceRecord;
|
|
356
278
|
}
|
|
357
|
-
//#endregion
|
|
358
|
-
//#region src/core/resolve/index.d.ts
|
|
359
279
|
/**
|
|
360
280
|
* Resolve parsed values against a command schema.
|
|
361
281
|
*
|
|
@@ -376,12 +296,21 @@ interface ResolveResult {
|
|
|
376
296
|
* a value. Collects **all** validation errors before throwing, so the
|
|
377
297
|
* user sees every missing field at once.
|
|
378
298
|
*
|
|
299
|
+
* `flag.path()` / `arg.path()` filesystem checks run only through the injected
|
|
300
|
+
* {@linkcode ResolveOptions.stat} probe. A check that cannot run is recorded in
|
|
301
|
+
* {@linkcode ResolveResult.skippedPathChecks}, or rejected outright when
|
|
302
|
+
* {@linkcode ResolveOptions.pathChecks} is `'strict'`.
|
|
303
|
+
*
|
|
379
304
|
* @param schema - The command schema defining flags and args
|
|
380
305
|
* @param parsed - Raw parsed values from the parser
|
|
381
306
|
* @param options - External state for the resolution chain
|
|
382
307
|
* @returns Fully resolved flag and arg values
|
|
383
308
|
* @throws {@linkcode ValidationError} if any required flag or arg is missing,
|
|
384
309
|
* or if an env/config value fails coercion
|
|
310
|
+
* @throws {@linkcode CLIError} with code `'INVALID_SCHEMA'` when
|
|
311
|
+
* {@linkcode ResolveOptions.envPrefix} is empty or carries `=`, a brace, or NUL
|
|
312
|
+
* @throws {@linkcode CLIError} with code `'PATH_CHECK_SKIPPED'` when
|
|
313
|
+
* `pathChecks: 'strict'` and a declared filesystem check could not run
|
|
385
314
|
*
|
|
386
315
|
* @example
|
|
387
316
|
* ```ts
|
|
@@ -392,8 +321,6 @@ interface ResolveResult {
|
|
|
392
321
|
* ```
|
|
393
322
|
*/
|
|
394
323
|
declare function resolve(schema: CommandSchema, parsed: ParseResult, options?: ResolveOptions): Promise<ResolveResult>;
|
|
395
|
-
//#endregion
|
|
396
|
-
//#region src/core/cli/plugin.d.ts
|
|
397
324
|
/** Shared hook payload for a concrete command execution. */
|
|
398
325
|
interface PluginCommandContext {
|
|
399
326
|
/** Runtime command schema being executed. */
|
|
@@ -416,6 +343,12 @@ interface ResolvedCommandParams extends PluginCommandContext {
|
|
|
416
343
|
readonly args: Readonly<Record<string, unknown>>;
|
|
417
344
|
/** Structured deprecation warnings collected during resolution. */
|
|
418
345
|
readonly deprecations: readonly DeprecationWarning[];
|
|
346
|
+
/**
|
|
347
|
+
* Declared `flag.path()` / `arg.path()` checks that could not run because
|
|
348
|
+
* execution supplied no `stat` probe (or no `mkdir` for `create`). Always
|
|
349
|
+
* empty under `CLIBuilder.run()`, which supplies the adapter's filesystem.
|
|
350
|
+
*/
|
|
351
|
+
readonly skippedPathChecks: readonly SkippedPathCheck[];
|
|
419
352
|
}
|
|
420
353
|
/**
|
|
421
354
|
* Individual lifecycle hooks that a plugin may implement.
|
|
@@ -482,8 +415,6 @@ interface CLIPlugin {
|
|
|
482
415
|
* @returns A frozen {@link CLIPlugin} definition.
|
|
483
416
|
*/
|
|
484
417
|
declare function plugin(hooks: CLIPluginHooks, name?: string): CLIPlugin;
|
|
485
|
-
//#endregion
|
|
486
|
-
//#region src/core/help/index.d.ts
|
|
487
418
|
/** Options for customising help output. */
|
|
488
419
|
interface HelpOptions {
|
|
489
420
|
/** Maximum line width (columns). Defaults to 80. */
|
|
@@ -510,6 +441,28 @@ interface HelpOptions {
|
|
|
510
441
|
* @defaultValue `undefined` (use `flagOrder`)
|
|
511
442
|
*/
|
|
512
443
|
readonly sortFlags?: (a: string, b: string) => number;
|
|
444
|
+
/**
|
|
445
|
+
* Spelling of long flag names, aliases, and negations in the `Flags:` table.
|
|
446
|
+
*
|
|
447
|
+
* - `'declared'` — each spelling exactly as it was declared.
|
|
448
|
+
* - `'kebab'` — the kebab-case counterpart of a camelCase spelling
|
|
449
|
+
* (`--wasm-path` for a flag keyed `wasmPath`), while the resolved value
|
|
450
|
+
* keeps its declared key. A spelling stays as declared when the parser
|
|
451
|
+
* would not read the counterpart as the same flag form: with
|
|
452
|
+
* {@link HelpOptions.caseParity} off, or when another declared flag owns it.
|
|
453
|
+
*
|
|
454
|
+
* @defaultValue `'declared'`
|
|
455
|
+
*/
|
|
456
|
+
readonly flagSpelling?: 'declared' | 'kebab';
|
|
457
|
+
/**
|
|
458
|
+
* Whether the parser accepts kebab↔camel counterpart spellings, so
|
|
459
|
+
* `flagSpelling: 'kebab'` only renders spellings the parser accepts.
|
|
460
|
+
* `CLIBuilder.execute()`/`.run()` and `readFlags()` thread their parser
|
|
461
|
+
* settings here automatically.
|
|
462
|
+
*
|
|
463
|
+
* @defaultValue `true`
|
|
464
|
+
*/
|
|
465
|
+
readonly caseParity?: boolean;
|
|
513
466
|
/**
|
|
514
467
|
* Emit OSC 8 hyperlinks where link metadata is available (currently the
|
|
515
468
|
* root-help header name/version configured via `CLIBuilder.links()`).
|
|
@@ -544,6 +497,14 @@ interface HelpOptions {
|
|
|
544
497
|
readonly footer?: boolean;
|
|
545
498
|
/** @internal Whether this usage line is being rendered as merged root/default help. */
|
|
546
499
|
readonly isDefaultHelp?: boolean;
|
|
500
|
+
/**
|
|
501
|
+
* Environment namespace applied to relative env bindings in `[env: …]`
|
|
502
|
+
* annotations, so help names the variables resolution actually reads.
|
|
503
|
+
* `CLIBuilder.execute()`/`.run()` thread the CLI's `.envPrefix()` here.
|
|
504
|
+
*
|
|
505
|
+
* @defaultValue `undefined` (names render as declared)
|
|
506
|
+
*/
|
|
507
|
+
readonly envPrefix?: string;
|
|
547
508
|
/**
|
|
548
509
|
* Gated ANSI palette used to style help output. Identity formatters mean
|
|
549
510
|
* plain text. `CLIBuilder.execute()`/`.run()` thread the output channel's
|
|
@@ -595,8 +556,6 @@ interface HelpOptions {
|
|
|
595
556
|
* ```
|
|
596
557
|
*/
|
|
597
558
|
declare function formatHelp(schema: CommandSchema, options?: HelpOptions): string;
|
|
598
|
-
//#endregion
|
|
599
|
-
//#region src/core/prompt/test-prompter.d.ts
|
|
600
559
|
/**
|
|
601
560
|
* Sentinel value representing a cancelled/aborted prompt in the test
|
|
602
561
|
* prompter's answer queue.
|
|
@@ -616,10 +575,10 @@ declare const PROMPT_CANCEL: unique symbol;
|
|
|
616
575
|
/**
|
|
617
576
|
* A queued answer consumed by {@link createTestPrompter}.
|
|
618
577
|
*
|
|
619
|
-
* The test prompter
|
|
620
|
-
*
|
|
621
|
-
*
|
|
622
|
-
*
|
|
578
|
+
* The test prompter leaves malformed non-string values intact for resolver
|
|
579
|
+
* error tests. Text answers use the same whitespace, empty-answer, default,
|
|
580
|
+
* and validation policy as the terminal prompter. Passwords retry invalid
|
|
581
|
+
* answers; ordinary input retains its cancellation fallback (see {@link createTestPrompter}).
|
|
623
582
|
* The normal resolution pipeline performs any later type coercion, so tests can
|
|
624
583
|
* supply values in the same shapes real prompts would yield:
|
|
625
584
|
*
|
|
@@ -658,6 +617,11 @@ interface TestPrompterOptions {
|
|
|
658
617
|
* is rejected as a cancellation (`{ answered: false }`) — mirroring the terminal
|
|
659
618
|
* prompter exhausting its retries — so prompt validation is integration-testable
|
|
660
619
|
* via {@linkcode runCommand} rather than silently accepted as the resolved value.
|
|
620
|
+
* Password prompts instead consume further queued answers on validation failure,
|
|
621
|
+
* and reject with `PROMPT_INVALID` after ten invalid attempts. Input prompts
|
|
622
|
+
* also retry empty answers when `empty: 'retry'`; ordinary validator failures
|
|
623
|
+
* retain their cancellation fallback. `PROMPT_CANCEL`
|
|
624
|
+
* remains a distinct user cancellation.
|
|
661
625
|
*
|
|
662
626
|
* @param answers - Ordered queue of answers. Use `PROMPT_CANCEL` for
|
|
663
627
|
* cancellation.
|
|
@@ -674,8 +638,6 @@ interface TestPrompterOptions {
|
|
|
674
638
|
* ```
|
|
675
639
|
*/
|
|
676
640
|
declare function createTestPrompter(answers: readonly TestAnswer[], options?: TestPrompterOptions): PromptEngine;
|
|
677
|
-
//#endregion
|
|
678
|
-
//#region src/core/schema/run.d.ts
|
|
679
641
|
/**
|
|
680
642
|
* Options accepted by `runCommand()` and internal command execution paths.
|
|
681
643
|
*
|
|
@@ -735,7 +697,9 @@ interface RunOptions {
|
|
|
735
697
|
*
|
|
736
698
|
* `CLIBuilder.run()` supplies the runtime adapter's probe automatically.
|
|
737
699
|
* When absent (process-free `.execute()` / `runCommand()` without an
|
|
738
|
-
* override), path checks are skipped
|
|
700
|
+
* override), path checks are skipped and each skipped input is listed in
|
|
701
|
+
* {@linkcode RunResult.skippedPathChecks}; set
|
|
702
|
+
* {@linkcode RunOptions.pathChecks} to `'strict'` to fail instead.
|
|
739
703
|
*/
|
|
740
704
|
readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
|
|
741
705
|
/**
|
|
@@ -743,9 +707,41 @@ interface RunOptions {
|
|
|
743
707
|
* checks.
|
|
744
708
|
*
|
|
745
709
|
* `CLIBuilder.run()` supplies the runtime adapter's implementation
|
|
746
|
-
* automatically. When absent, missing paths are not created
|
|
710
|
+
* automatically. When absent, missing paths are not created: the existence
|
|
711
|
+
* rules decide instead, and the input is listed in
|
|
712
|
+
* {@linkcode RunResult.skippedPathChecks} with `missing: 'mkdir'`.
|
|
747
713
|
*/
|
|
748
714
|
readonly mkdir?: (path: string) => Promise<void>;
|
|
715
|
+
/**
|
|
716
|
+
* What happens to a declared filesystem check that cannot run because
|
|
717
|
+
* `stat` (or `mkdir` for `create`) was not supplied.
|
|
718
|
+
*
|
|
719
|
+
* - `'lenient'` — skip the check and record it in
|
|
720
|
+
* {@linkcode RunResult.skippedPathChecks}; the command still runs, which
|
|
721
|
+
* keeps parser and action tests off the host filesystem.
|
|
722
|
+
* - `'strict'` — fail with a `CLIError` of code `'PATH_CHECK_SKIPPED'`
|
|
723
|
+
* (exit code `1`) naming every input whose check did not run, so a
|
|
724
|
+
* passing test proves each declared `mustExist`, `type`, and `create`
|
|
725
|
+
* check was exercised.
|
|
726
|
+
*
|
|
727
|
+
* Only inputs that resolved a path value count. `CLIBuilder.run()` always
|
|
728
|
+
* supplies the adapter's filesystem, so this matters to `.execute()` and
|
|
729
|
+
* `runCommand()`.
|
|
730
|
+
*
|
|
731
|
+
* @defaultValue `'lenient'`
|
|
732
|
+
*/
|
|
733
|
+
readonly pathChecks?: 'lenient' | 'strict';
|
|
734
|
+
/**
|
|
735
|
+
* Environment namespace prepended to every relative `.env()` binding, the
|
|
736
|
+
* same way `CLIBuilder.envPrefix()` applies one CLI-wide.
|
|
737
|
+
*
|
|
738
|
+
* `.execute()` and `.run()` default it to the CLI's own prefix, and a value
|
|
739
|
+
* here wins. Pass it to `runCommand()` to test a command under the namespace
|
|
740
|
+
* its CLI declares; without it a command reads its env names as written.
|
|
741
|
+
*
|
|
742
|
+
* @defaultValue `undefined` (no namespace)
|
|
743
|
+
*/
|
|
744
|
+
readonly envPrefix?: string;
|
|
749
745
|
/**
|
|
750
746
|
* Verbosity level for the output channel.
|
|
751
747
|
* @defaultValue `'normal'`
|
|
@@ -826,6 +822,16 @@ interface RunResult {
|
|
|
826
822
|
* unknown errors are wrapped.
|
|
827
823
|
*/
|
|
828
824
|
readonly error: CLIError | undefined;
|
|
825
|
+
/**
|
|
826
|
+
* Declared `flag.path()` / `arg.path()` checks that did not run because no
|
|
827
|
+
* `stat` probe (or no `mkdir` for `create`) was supplied.
|
|
828
|
+
*
|
|
829
|
+
* Empty when every declared check ran, when no resolved value had a check
|
|
830
|
+
* to run, or when execution ended before resolution. A successful result
|
|
831
|
+
* with entries here never consulted the filesystem, so it does not prove
|
|
832
|
+
* the real CLI accepts the same path — pass `stat` / `mkdir`, or set
|
|
833
|
+
* {@linkcode RunOptions.pathChecks} to `'strict'` to make the test fail.
|
|
834
|
+
*/
|
|
835
|
+
readonly skippedPathChecks: readonly SkippedPathCheck[];
|
|
829
836
|
}
|
|
830
|
-
|
|
831
|
-
export { ErrorCode as A, BuiltinMode as B, includesBeforeSeparator as C, CLIError as D, tokenize as E, ValidationErrorCode as F, Builtins as H, ValidationErrorOptions as I, isCLIError as L, ParseErrorCode as M, ParseErrorOptions as N, CLIErrorJSON as O, ValidationError as P, isParseError as R, Token as S, stripBeforeSeparator as T, BuiltinsConfig as U, BuiltinName as V, ResolutionProvenanceRecord as _, TestPrompterOptions as a, ParseOptions as b, formatHelp as c, CLIPluginHooks as d, PluginCommandContext as f, DeprecationWarning as g, resolve as h, TestAnswer as i, ParseError as j, CLIErrorOptions as k, BeforeParseParams as l, plugin as m, RunResult as n, createTestPrompter as o, ResolvedCommandParams as p, PROMPT_CANCEL as r, HelpOptions as s, RunOptions as t, CLIPlugin as u, ResolveOptions as v, parse as w, ParseResult as x, ResolveResult as y, isValidationError as z };
|
|
837
|
+
export { Builtins as A, Token as C, tokenize as D, stripBeforeSeparator as E, BuiltinMode as O, ParseResult as S, parse as T, ResolutionProvenanceRecord as _, TestPrompterOptions as a, SkippedPathCheck as b, formatHelp as c, CLIPluginHooks as d, PluginCommandContext as f, DeprecationWarning as g, resolve as h, TestAnswer as i, BuiltinsConfig as j, BuiltinName as k, BeforeParseParams as l, plugin as m, RunResult as n, createTestPrompter as o, ResolvedCommandParams as p, PROMPT_CANCEL as r, HelpOptions as s, RunOptions as t, CLIPlugin as u, ResolveOptions as v, includesBeforeSeparator as w, ParseOptions as x, ResolveResult as y };
|
|
@@ -1,9 +1,8 @@
|
|
|
1
|
-
import { C as ErasedActionHandler, E as ExecutionStep,
|
|
2
|
-
import {
|
|
3
|
-
import { n as RuntimeAdapter } from "./adapter-
|
|
4
|
-
import { h as PackageJsonData, s as FormatLoader } from "./index-
|
|
1
|
+
import { C as ErasedActionHandler, E as ExecutionStep, Gn as HelpThemeFactory, It as FlagBuilder, J as ArgConfig, K as Verbosity, Lt as FlagConfig, _ as CommandDefinition, b as CommandSchema, g as CommandBuilder, nr as schemaBrand, q as ArgBuilder } from "./index-BIMjOsR6.mjs";
|
|
2
|
+
import { A as Builtins, j as BuiltinsConfig, n as RunResult, t as RunOptions, u as CLIPlugin, x as ParseOptions } from "./index-DpslpOVV.mjs";
|
|
3
|
+
import { n as RuntimeAdapter } from "./adapter-DBeedKmD.mjs";
|
|
4
|
+
import { h as PackageJsonData, s as FormatLoader } from "./index-jq_FJRKt.mjs";
|
|
5
5
|
import { Colors } from "ansispeck";
|
|
6
|
-
//#region src/core/completion/shells/shared.d.ts
|
|
7
6
|
/**
|
|
8
7
|
* Options for completion script generation.
|
|
9
8
|
*
|
|
@@ -40,8 +39,6 @@ interface CompletionOptions {
|
|
|
40
39
|
*/
|
|
41
40
|
readonly rootMode?: 'subcommands' | 'surface';
|
|
42
41
|
}
|
|
43
|
-
//#endregion
|
|
44
|
-
//#region src/core/completion/shell.d.ts
|
|
45
42
|
/**
|
|
46
43
|
* Supported shell targets for completion script generation.
|
|
47
44
|
*
|
|
@@ -58,8 +55,6 @@ type Shell = 'bash' | 'zsh' | 'fish' | 'powershell';
|
|
|
58
55
|
* @see {@link Shell} for the union type matching these entries.
|
|
59
56
|
*/
|
|
60
57
|
declare const SHELLS: Readonly<readonly ['bash', 'zsh', 'fish', 'powershell']>;
|
|
61
|
-
//#endregion
|
|
62
|
-
//#region src/core/cli/compiled.d.ts
|
|
63
58
|
/**
|
|
64
59
|
* Executable form of one registered command.
|
|
65
60
|
*/
|
|
@@ -84,8 +79,6 @@ interface CompiledCLI {
|
|
|
84
79
|
/** Plugins in registration order. */
|
|
85
80
|
readonly plugins: readonly CLIPlugin[];
|
|
86
81
|
}
|
|
87
|
-
//#endregion
|
|
88
|
-
//#region src/core/cli/help-links.d.ts
|
|
89
82
|
/**
|
|
90
83
|
* OSC 8 hyperlink targets for the root-help header.
|
|
91
84
|
*
|
|
@@ -98,8 +91,6 @@ interface HelpLinks {
|
|
|
98
91
|
/** URL the version links to (e.g. the release tag). */
|
|
99
92
|
readonly version: string | undefined;
|
|
100
93
|
}
|
|
101
|
-
//#endregion
|
|
102
|
-
//#region src/core/cli/index.d.ts
|
|
103
94
|
/**
|
|
104
95
|
* Runtime descriptor for the CLI program.
|
|
105
96
|
*
|
|
@@ -201,6 +192,16 @@ interface CLISchema {
|
|
|
201
192
|
* releases its tokens to the commands.
|
|
202
193
|
*/
|
|
203
194
|
readonly builtins: Builtins;
|
|
195
|
+
/**
|
|
196
|
+
* CLI-wide environment namespace prepended to every relative env binding
|
|
197
|
+
* (`undefined` when none is set). `.env('TOKEN')` reads `<envPrefix>TOKEN`;
|
|
198
|
+
* a binding declared with `{ absolute: true }` is read as written.
|
|
199
|
+
*
|
|
200
|
+
* Set via the {@linkcode CLIBuilder.envPrefix | .envPrefix()} builder method
|
|
201
|
+
* or the `envPrefix` field of {@link CLIDefinition}. Fixed when declared, so
|
|
202
|
+
* neither manifest name inference nor an inherited invocation name changes it.
|
|
203
|
+
*/
|
|
204
|
+
readonly envPrefix: string | undefined;
|
|
204
205
|
}
|
|
205
206
|
/**
|
|
206
207
|
* Options for {@link CLIBuilder.completions}: the generator options plus where
|
|
@@ -280,6 +281,17 @@ interface HelpConfig {
|
|
|
280
281
|
* @defaultValue `undefined` (use `flagOrder`)
|
|
281
282
|
*/
|
|
282
283
|
readonly sortFlags?: (a: string, b: string) => number;
|
|
284
|
+
/**
|
|
285
|
+
* Spelling of long flag names, aliases, and negations in the `Flags:` table.
|
|
286
|
+
*
|
|
287
|
+
* `'kebab'` shows `--wasm-path` for a flag keyed `wasmPath` while handlers
|
|
288
|
+
* keep reading `flags.wasmPath`. A spelling stays as declared when the
|
|
289
|
+
* parser would not accept its kebab form for the same flag, such as under
|
|
290
|
+
* `cli(name, { flags: { caseParity: false } })`.
|
|
291
|
+
*
|
|
292
|
+
* @defaultValue `'declared'`
|
|
293
|
+
*/
|
|
294
|
+
readonly flagSpelling?: 'declared' | 'kebab';
|
|
283
295
|
/**
|
|
284
296
|
* Theme overrides for help output, merged over the built-in theme.
|
|
285
297
|
*
|
|
@@ -466,6 +478,12 @@ interface CLIDefinition {
|
|
|
466
478
|
* @defaultValue every built-in `'on'`
|
|
467
479
|
*/
|
|
468
480
|
readonly builtins?: BuiltinsConfig | undefined;
|
|
481
|
+
/**
|
|
482
|
+
* CLI-wide environment namespace for relative env bindings, used verbatim
|
|
483
|
+
* (`'ACME_'` turns `TOKEN` into `ACME_TOKEN`).
|
|
484
|
+
* @defaultValue `undefined` (no namespace)
|
|
485
|
+
*/
|
|
486
|
+
readonly envPrefix?: string | undefined;
|
|
469
487
|
/**
|
|
470
488
|
* Registered command definitions or built schemas, in registration order.
|
|
471
489
|
* @defaultValue `[]`
|
|
@@ -721,6 +739,40 @@ declare class CLIBuilder {
|
|
|
721
739
|
* `--version` or `-V` as a flag name, an alias, or a negated spelling.
|
|
722
740
|
*/
|
|
723
741
|
version(v: string): CLIBuilder;
|
|
742
|
+
/**
|
|
743
|
+
* Namespace every relative env binding under one CLI-wide prefix.
|
|
744
|
+
*
|
|
745
|
+
* With no argument the prefix is derived from the name passed to `cli()`:
|
|
746
|
+
* camelCase word boundaries and each run of characters outside
|
|
747
|
+
* `[A-Za-z0-9]` become `_`, the result is uppercased with leading and
|
|
748
|
+
* trailing separators dropped, and `_` is appended (`foo-bar` and `fooBar`
|
|
749
|
+
* → `FOO_BAR_`). This is the rule a name-derived `.env()` follows, minus
|
|
750
|
+
* the trailing `_`. An explicit prefix is used verbatim. Either way it is fixed
|
|
751
|
+
* here, so a manifest-inferred name or an inherited invocation name (a
|
|
752
|
+
* symlink, an alias, `npx`) never changes the environment API.
|
|
753
|
+
*
|
|
754
|
+
* Every `.env()` binding on every command then reads the prefixed name, an
|
|
755
|
+
* indexed family's count and templates included, unless declared with
|
|
756
|
+
* `{ absolute: true }`. Precedence, coercion, and validation are unchanged;
|
|
757
|
+
* help, diagnostics, and `sources` name the concrete variable.
|
|
758
|
+
*
|
|
759
|
+
* @param prefix - The namespace to use verbatim, or omit it to derive one.
|
|
760
|
+
* @returns The builder (for chaining).
|
|
761
|
+
* @throws {CLIError} With code `'INVALID_SCHEMA'` when the prefix is empty or
|
|
762
|
+
* carries `=`, a brace, or NUL, or when no prefix can be derived from the name.
|
|
763
|
+
*
|
|
764
|
+
* @example
|
|
765
|
+
* ```ts
|
|
766
|
+
* cli('foo')
|
|
767
|
+
* .envPrefix()
|
|
768
|
+
* .command(
|
|
769
|
+
* command('deploy')
|
|
770
|
+
* .flag('token', flag.string().env('TOKEN')) // FOO_TOKEN
|
|
771
|
+
* .flag('home', flag.path().env('HOME', { absolute: true })), // HOME
|
|
772
|
+
* );
|
|
773
|
+
* ```
|
|
774
|
+
*/
|
|
775
|
+
envPrefix(prefix?: string): CLIBuilder;
|
|
724
776
|
/**
|
|
725
777
|
* Choose which built-in flags the root keeps.
|
|
726
778
|
*
|
|
@@ -1231,5 +1283,4 @@ declare function cli(options: CLIOptions): CLIBuilder;
|
|
|
1231
1283
|
* ```
|
|
1232
1284
|
*/
|
|
1233
1285
|
declare function isMainModule(meta: ImportMeta): boolean;
|
|
1234
|
-
//#endregion
|
|
1235
1286
|
export { SHELLS as C, HelpLinks as S, CompletionOptions as T, ResolvedManifestSettings as _, CLIRunOptions as a, isMainModule as b, CompletionsFlagConfig as c, DefaultCommandOptions as d, HelpConfig as f, RenderContextOptions as g, RenderContext as h, CLIOptions as i, ConfigSettings as l, ManifestSettings as m, CLIDefinition as n, CLISchema as o, InferNameOption as p, CLIExecuteOptions as r, CompletionRegistrationOptions as s, CLIBuilder as t, ConfigSettingsDefinition as u, cli as v, Shell as w, resolveRenderContext as x, createCLISchema as y };
|
|
@@ -1,5 +1,4 @@
|
|
|
1
|
-
import { n as RuntimeAdapter } from "./adapter-
|
|
2
|
-
//#region src/core/config/package-json.d.ts
|
|
1
|
+
import { n as RuntimeAdapter } from "./adapter-DBeedKmD.mjs";
|
|
3
2
|
/**
|
|
4
3
|
* Object form of a manifest's `repository` field
|
|
5
4
|
* (e.g. `{"type":"git","url":"git+https://github.com/u/r.git"}`).
|
|
@@ -132,8 +131,6 @@ declare function discoverManifest(adapter: PackageJsonAdapter, options?: Manifes
|
|
|
132
131
|
declare function inferCliName(pkg: PackageJsonData, options?: {
|
|
133
132
|
readonly stripScope?: boolean;
|
|
134
133
|
}): string | undefined;
|
|
135
|
-
//#endregion
|
|
136
|
-
//#region src/core/config/repository-url.d.ts
|
|
137
134
|
/** Options for {@link packageRepositoryUrl}. */
|
|
138
135
|
interface PackageRepositoryUrlOptions {
|
|
139
136
|
/**
|
|
@@ -178,8 +175,6 @@ declare function packageRepositoryUrl(pkg: PackageJsonData, options: PackageRepo
|
|
|
178
175
|
}): string;
|
|
179
176
|
/** Resolve a manifest repository URL, returning `undefined` for absent or invalid locators. */
|
|
180
177
|
declare function packageRepositoryUrl(pkg: PackageJsonData, options?: PackageRepositoryUrlOptions): string | undefined;
|
|
181
|
-
//#endregion
|
|
182
|
-
//#region src/core/config/index.d.ts
|
|
183
178
|
/**
|
|
184
179
|
* Format loader — parses file content into a config object.
|
|
185
180
|
*
|
|
@@ -366,5 +361,4 @@ declare function discoverConfig(appName: string, adapter: ConfigAdapter, options
|
|
|
366
361
|
* ```
|
|
367
362
|
*/
|
|
368
363
|
declare function configFormat(extensions: readonly string[], parse: (content: string) => unknown): FormatLoader;
|
|
369
|
-
//#endregion
|
|
370
364
|
export { discoverManifest as _, ConfigNotFound as a, buildConfigSearchPaths as c, PackageRepositoryUrlOptions as d, packageRepositoryUrl as f, PackageRepository as g, PackageJsonData as h, ConfigFound as i, configFormat as l, PackageJsonAdapter as m, ConfigDiscoveryOptions as n, ConfigSearchPathOptions as o, ManifestDiscoveryOptions as p, ConfigDiscoveryResult as r, FormatLoader as s, ConfigAdapter as t, discoverConfig as u, inferCliName as v };
|