@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,11 @@
|
|
|
1
|
+
import { schemaBrand } from "./brand.mjs";
|
|
2
|
+
import { Verbosity } from "../output/contracts.mjs";
|
|
1
3
|
import { ProgressHandle, ProgressOptions, SpinnerHandle, SpinnerOptions, TableColumn, TableOptions } from "./activity.mjs";
|
|
2
|
-
import { ArgBuilder, ArgConfig, ArgSchema, InferArgs } from "./arg.mjs";
|
|
3
4
|
import { PromptConfig } from "./prompt.mjs";
|
|
4
|
-
import { FlagBuilder, FlagConfig, FlagSchema, InferFlags } from "./flag.mjs";
|
|
5
|
+
import { FlagBuilder, FlagConfig, FlagDefinition, FlagSchema, InferFlags } from "./flag.mjs";
|
|
6
|
+
import { ArgBuilder, ArgConfig, ArgDefinition, ArgSchema, InferArgs } from "./arg.mjs";
|
|
5
7
|
import { ErasedMiddlewareHandler, Middleware } from "./middleware.mjs";
|
|
6
|
-
import {
|
|
8
|
+
import { InputSources } from "./provenance.mjs";
|
|
7
9
|
import { Colors } from "ansispeck";
|
|
8
10
|
//#region src/core/schema/command.d.ts
|
|
9
11
|
/**
|
|
@@ -26,18 +28,6 @@ type WidenContext<C extends Record<string, unknown>, Output extends Record<strin
|
|
|
26
28
|
* using the same first-call replacement rules as middleware.
|
|
27
29
|
*/
|
|
28
30
|
type WidenDerivedContext<C extends Record<string, unknown>, Output> = Awaited<Output> extends Record<string, unknown> ? WidenContext<C, Awaited<Output>> : C;
|
|
29
|
-
/**
|
|
30
|
-
* Compile-time state carried through the command builder chain.
|
|
31
|
-
*
|
|
32
|
-
* `F` accumulates named flag builders; `A` accumulates named arg builders.
|
|
33
|
-
* Both start empty (`{}`) and grow as `.flag()` / `.arg()` are called.
|
|
34
|
-
*/
|
|
35
|
-
interface CommandConfig {
|
|
36
|
-
/** Accumulated flag builders keyed by flag name. */
|
|
37
|
-
readonly flags: Record<string, FlagBuilder<FlagConfig>>;
|
|
38
|
-
/** Accumulated arg builders keyed by arg name. */
|
|
39
|
-
readonly args: Record<string, ArgBuilder<ArgConfig>>;
|
|
40
|
-
}
|
|
41
31
|
/**
|
|
42
32
|
* Parameters received by the interactive resolver function.
|
|
43
33
|
*
|
|
@@ -58,7 +48,7 @@ interface InteractiveParams<F extends Record<string, FlagBuilder<FlagConfig>>> {
|
|
|
58
48
|
* Only flag names that need prompting should have truthy values.
|
|
59
49
|
* Flags not mentioned are handled by their per-flag `.prompt()` config.
|
|
60
50
|
*/
|
|
61
|
-
type InteractiveResult = Readonly<Record<string, PromptConfig | false | undefined | null | 0 |
|
|
51
|
+
type InteractiveResult = Readonly<Record<string, PromptConfig | false | undefined | null | 0 | "">>;
|
|
62
52
|
/**
|
|
63
53
|
* Interactive resolver function for command-level prompt control.
|
|
64
54
|
*
|
|
@@ -94,8 +84,6 @@ type InteractiveResolver<F extends Record<string, FlagBuilder<FlagConfig>>> = (p
|
|
|
94
84
|
* At runtime, the resolver receives `{ flags: Record<string, unknown> }`
|
|
95
85
|
* and returns `Record<string, PromptConfig | falsy>`. The phantom types
|
|
96
86
|
* from `CommandBuilder<F, A>` are erased.
|
|
97
|
-
*
|
|
98
|
-
* @internal
|
|
99
87
|
*/
|
|
100
88
|
type ErasedInteractiveResolver = (params: {
|
|
101
89
|
readonly flags: Readonly<Record<string, unknown>>;
|
|
@@ -106,8 +94,14 @@ type ErasedInteractiveResolver = (params: {
|
|
|
106
94
|
* Provides structured methods for stdout/stderr, JSON output,
|
|
107
95
|
* spinners, progress bars, and tables. The real implementation lives in
|
|
108
96
|
* `src/core/output/`; this interface defines the shape that handlers consume.
|
|
97
|
+
*
|
|
98
|
+
* `Out` is a framework-created, non-exhaustive value: obtain instances from
|
|
99
|
+
* action parameters, `createOutput()`, or `createCaptureOutput()` — do not
|
|
100
|
+
* implement it. New readonly members may be added in minor releases.
|
|
109
101
|
*/
|
|
110
102
|
interface Out {
|
|
103
|
+
/** Framework-construction seal. Obtain `Out` values from DreamCLI; do not implement this interface. */
|
|
104
|
+
readonly [outBrand]: never;
|
|
111
105
|
/** Write to stdout (normal output). */
|
|
112
106
|
log(message: string): void;
|
|
113
107
|
/** Informational (may be suppressed in quiet mode). */
|
|
@@ -148,6 +142,17 @@ interface Out {
|
|
|
148
142
|
* expected.
|
|
149
143
|
*/
|
|
150
144
|
readonly jsonMode: boolean;
|
|
145
|
+
/**
|
|
146
|
+
* Active output verbosity for this command execution.
|
|
147
|
+
*
|
|
148
|
+
* Root `--quiet`/`-q` resolves to `'quiet'`. Most handlers should emit
|
|
149
|
+
* informational output through {@linkcode Out.info | info()},
|
|
150
|
+
* {@linkcode Out.status | status()}, {@linkcode Out.spinner | spinner()},
|
|
151
|
+
* or {@linkcode Out.progress | progress()} and let the channel suppress it
|
|
152
|
+
* automatically. Read this property only when custom rendering or expensive
|
|
153
|
+
* optional work genuinely depends on the active verbosity.
|
|
154
|
+
*/
|
|
155
|
+
readonly verbosity: Verbosity;
|
|
151
156
|
/**
|
|
152
157
|
* Whether stdout is connected to a TTY (terminal).
|
|
153
158
|
*
|
|
@@ -215,8 +220,8 @@ interface Out {
|
|
|
215
220
|
/**
|
|
216
221
|
* Create a spinner for indeterminate progress feedback.
|
|
217
222
|
*
|
|
218
|
-
* Returns a handle
|
|
219
|
-
*
|
|
223
|
+
* Returns a no-op handle in quiet or JSON mode. Otherwise, non-TTY output
|
|
224
|
+
* uses a no-op handle or the configured static fallback.
|
|
220
225
|
*
|
|
221
226
|
* @param text - Initial spinner text.
|
|
222
227
|
* @param options - Fallback strategy for non-TTY environments.
|
|
@@ -226,7 +231,7 @@ interface Out {
|
|
|
226
231
|
/**
|
|
227
232
|
* Create a progress bar for measured work.
|
|
228
233
|
*
|
|
229
|
-
* Returns a handle
|
|
234
|
+
* Returns a no-op handle in quiet or JSON mode. Otherwise, pass `total` for
|
|
230
235
|
* determinate mode (percentage bar); omit for indeterminate (pulsing).
|
|
231
236
|
*
|
|
232
237
|
* @param options - Progress configuration (total, label, fallback).
|
|
@@ -283,11 +288,12 @@ interface CommandMeta {
|
|
|
283
288
|
/**
|
|
284
289
|
* The bag of values received by an action handler.
|
|
285
290
|
*
|
|
286
|
-
* - `args
|
|
287
|
-
* - `flags
|
|
288
|
-
* - `
|
|
289
|
-
* - `
|
|
290
|
-
* - `
|
|
291
|
+
* - `args`: fully resolved positional arguments
|
|
292
|
+
* - `flags`: fully resolved flags
|
|
293
|
+
* - `sources`: which stage produced each of those values
|
|
294
|
+
* - `ctx`: derive/middleware-provided context
|
|
295
|
+
* - `out`: output channel
|
|
296
|
+
* - `meta`: CLI program metadata (name, bin, version, command)
|
|
291
297
|
*
|
|
292
298
|
* The `C` parameter defaults to `Record<string, never>`, making `ctx`
|
|
293
299
|
* property access a type error until derive or middleware extends it.
|
|
@@ -297,6 +303,13 @@ interface ActionParams<F extends Record<string, FlagBuilder<FlagConfig>>, A exte
|
|
|
297
303
|
readonly args: Readonly<InferArgs<A>>;
|
|
298
304
|
/** Fully resolved flag values, typed from `.flag()` definitions. */
|
|
299
305
|
readonly flags: Readonly<InferFlags<F>>;
|
|
306
|
+
/**
|
|
307
|
+
* Where each resolved value came from, keyed like `flags` and `args`.
|
|
308
|
+
*
|
|
309
|
+
* An input that resolved no value has no record. {@link wasExplicit} answers
|
|
310
|
+
* the explicit-versus-defaulted question; read `stage` for the rest.
|
|
311
|
+
*/
|
|
312
|
+
readonly sources: InputSources<F, A>;
|
|
300
313
|
/** Middleware/derive-provided context, typed from `.middleware()` and `.derive()` chains. */
|
|
301
314
|
readonly ctx: Readonly<C>;
|
|
302
315
|
/** Structured output channel for stdout, stderr, JSON, tables, and spinners. */
|
|
@@ -323,22 +336,26 @@ type ActionHandler<F extends Record<string, FlagBuilder<FlagConfig>>, A extends
|
|
|
323
336
|
*
|
|
324
337
|
* Follows the same erasure pattern as {@link ErasedDeriveHandler} and
|
|
325
338
|
* {@link ErasedMiddlewareHandler}.
|
|
326
|
-
*
|
|
327
|
-
* @internal
|
|
328
339
|
*/
|
|
329
340
|
type ErasedActionHandler = (params: {
|
|
330
341
|
readonly args: Readonly<Record<string, unknown>>;
|
|
331
342
|
readonly flags: Readonly<Record<string, unknown>>;
|
|
343
|
+
readonly sources: ErasedInputSources;
|
|
332
344
|
readonly ctx: Readonly<Record<string, unknown>>;
|
|
333
345
|
readonly out: Out;
|
|
334
346
|
readonly meta: CommandMeta;
|
|
335
347
|
}) => void | Promise<void>;
|
|
348
|
+
/**
|
|
349
|
+
* The provenance bag as the execution seam carries it, before a handler's own
|
|
350
|
+
* flag and arg names type it.
|
|
351
|
+
*/
|
|
352
|
+
type ErasedInputSources = InputSources<Readonly<Record<string, unknown>>, Readonly<Record<string, unknown>>>;
|
|
336
353
|
/**
|
|
337
354
|
* The bag of values received by a derive handler.
|
|
338
355
|
*
|
|
339
356
|
* Identical to {@link ActionParams}: derives run after full resolution and
|
|
340
|
-
* before the action handler, with typed args
|
|
341
|
-
* and `meta`.
|
|
357
|
+
* before the action handler, with typed args, flags, provenance, and current
|
|
358
|
+
* context plus `out` and `meta`.
|
|
342
359
|
*/
|
|
343
360
|
type DeriveParams<F extends Record<string, FlagBuilder<FlagConfig>>, A extends Record<string, ArgBuilder<ArgConfig>>, C extends Record<string, unknown> = Record<string, never>> = ActionParams<F, A, C>;
|
|
344
361
|
/**
|
|
@@ -355,12 +372,11 @@ type DeriveParams<F extends Record<string, FlagBuilder<FlagConfig>>, A extends R
|
|
|
355
372
|
type DeriveHandler<F extends Record<string, FlagBuilder<FlagConfig>>, A extends Record<string, ArgBuilder<ArgConfig>>, C extends Record<string, unknown> = Record<string, never>, Output extends Record<string, unknown> | undefined = undefined> = (params: DeriveParams<F, A, C>) => Output | Promise<Output> | void | Promise<void>;
|
|
356
373
|
/**
|
|
357
374
|
* Type-erased derive handler stored on the command builder.
|
|
358
|
-
*
|
|
359
|
-
* @internal
|
|
360
375
|
*/
|
|
361
376
|
type ErasedDeriveHandler = (params: {
|
|
362
377
|
readonly args: Readonly<Record<string, unknown>>;
|
|
363
378
|
readonly flags: Readonly<Record<string, unknown>>;
|
|
379
|
+
readonly sources: ErasedInputSources;
|
|
364
380
|
readonly ctx: Readonly<Record<string, unknown>>;
|
|
365
381
|
readonly out: Out;
|
|
366
382
|
readonly meta: CommandMeta;
|
|
@@ -368,14 +384,12 @@ type ErasedDeriveHandler = (params: {
|
|
|
368
384
|
/**
|
|
369
385
|
* Internal execution step union preserving registration order across
|
|
370
386
|
* {@linkcode CommandBuilder.derive | derive()} and {@linkcode CommandBuilder.middleware | middleware()}.
|
|
371
|
-
*
|
|
372
|
-
* @internal
|
|
373
387
|
*/
|
|
374
388
|
type ExecutionStep = {
|
|
375
|
-
readonly kind:
|
|
389
|
+
readonly kind: "derive";
|
|
376
390
|
readonly handler: ErasedDeriveHandler;
|
|
377
391
|
} | {
|
|
378
|
-
readonly kind:
|
|
392
|
+
readonly kind: "middleware";
|
|
379
393
|
readonly handler: ErasedMiddlewareHandler;
|
|
380
394
|
};
|
|
381
395
|
/**
|
|
@@ -410,9 +424,11 @@ declare function resolveExampleCommand(command: ExampleCommand, meta: ExampleMet
|
|
|
410
424
|
*
|
|
411
425
|
* Consumers (parser, help generator, CLI dispatcher) read this to
|
|
412
426
|
* understand the command's shape — flags, args, aliases, subcommands,
|
|
413
|
-
*
|
|
427
|
+
* and interactive resolver.
|
|
414
428
|
*/
|
|
415
429
|
interface CommandSchema {
|
|
430
|
+
/** Type-only seal produced by {@link createCommandSchema}. */
|
|
431
|
+
readonly [schemaBrand]: "command";
|
|
416
432
|
/** The command name (used for dispatch, e.g. `'deploy'`). */
|
|
417
433
|
readonly name: string;
|
|
418
434
|
/** Human-readable description for help text. */
|
|
@@ -440,15 +456,6 @@ interface CommandSchema {
|
|
|
440
456
|
* @see InteractiveResolver
|
|
441
457
|
*/
|
|
442
458
|
readonly interactive: ErasedInteractiveResolver | undefined;
|
|
443
|
-
/**
|
|
444
|
-
* Middleware handlers to run before the action handler.
|
|
445
|
-
*
|
|
446
|
-
* Executed in registration order — first middleware registered runs
|
|
447
|
-
* first and calls `next()` to proceed to subsequent middleware,
|
|
448
|
-
* ending with the action handler. Context accumulates via intersection
|
|
449
|
-
* at the type level and via object spread at runtime.
|
|
450
|
-
*/
|
|
451
|
-
readonly middleware: readonly ErasedMiddlewareHandler[];
|
|
452
459
|
/**
|
|
453
460
|
* Nested subcommand schemas (for help rendering and completion).
|
|
454
461
|
*
|
|
@@ -470,52 +477,125 @@ interface CommandArgEntry {
|
|
|
470
477
|
readonly schema: ArgSchema;
|
|
471
478
|
}
|
|
472
479
|
/**
|
|
473
|
-
* A
|
|
474
|
-
*
|
|
475
|
-
* Advanced/internal bridge type: most consumers should work with
|
|
476
|
-
* {@link CommandBuilder} and never reference `ErasedCommand` directly.
|
|
477
|
-
*
|
|
478
|
-
* Commands registered via `CLIBuilder.command()` have heterogeneous `F`, `A`,
|
|
479
|
-
* and `C` type parameters. At the dispatch level we only need the runtime
|
|
480
|
-
* schema (for name/alias matching and help) and the ability to delegate to
|
|
481
|
-
* `runCommand()`. This interface captures exactly that contract.
|
|
480
|
+
* A named positional argument entry accepted by {@link createCommandSchema}.
|
|
482
481
|
*
|
|
483
|
-
* The
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
482
|
+
* The schema may be an {@link ArgDefinition} or an already-built {@link ArgSchema}.
|
|
483
|
+
*/
|
|
484
|
+
interface CommandArgEntryDefinition {
|
|
485
|
+
/** User-facing argument name (shown in help as `<name>`). */
|
|
486
|
+
readonly name: string;
|
|
487
|
+
/** Arg definition or an already-built schema. */
|
|
488
|
+
readonly schema: ArgDefinition | ArgSchema;
|
|
489
|
+
}
|
|
490
|
+
/**
|
|
491
|
+
* Input shape accepted by {@link createCommandSchema}.
|
|
489
492
|
*
|
|
490
|
-
*
|
|
493
|
+
* Every field except `name` is optional. Flags, args, and subcommands accept
|
|
494
|
+
* either definitions or already-built schemas.
|
|
491
495
|
*/
|
|
492
|
-
interface
|
|
493
|
-
/**
|
|
494
|
-
readonly
|
|
496
|
+
interface CommandDefinition {
|
|
497
|
+
/** The command name used for dispatch. */
|
|
498
|
+
readonly name: string;
|
|
495
499
|
/**
|
|
496
|
-
*
|
|
497
|
-
*
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
*
|
|
502
|
-
* @
|
|
500
|
+
* Human-readable description for help text.
|
|
501
|
+
* @defaultValue `undefined`
|
|
502
|
+
*/
|
|
503
|
+
readonly description?: string | undefined;
|
|
504
|
+
/**
|
|
505
|
+
* Alternative names for this command.
|
|
506
|
+
* @defaultValue `[]`
|
|
503
507
|
*/
|
|
504
|
-
readonly
|
|
505
|
-
/**
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
508
|
+
readonly aliases?: readonly string[] | undefined;
|
|
509
|
+
/**
|
|
510
|
+
* Whether this command is hidden from help listings.
|
|
511
|
+
* @defaultValue `false`
|
|
512
|
+
*/
|
|
513
|
+
readonly hidden?: boolean | undefined;
|
|
514
|
+
/**
|
|
515
|
+
* Usage examples for help text.
|
|
516
|
+
* @defaultValue `[]`
|
|
517
|
+
*/
|
|
518
|
+
readonly examples?: readonly CommandExample[] | undefined;
|
|
519
|
+
/**
|
|
520
|
+
* Flag definitions or built schemas, keyed by flag name.
|
|
521
|
+
* @defaultValue `{}`
|
|
522
|
+
*/
|
|
523
|
+
readonly flags?: Readonly<Record<string, FlagDefinition | FlagSchema>> | undefined;
|
|
524
|
+
/**
|
|
525
|
+
* Ordered positional arg entries.
|
|
526
|
+
* @defaultValue `[]`
|
|
527
|
+
*/
|
|
528
|
+
readonly args?: readonly CommandArgEntryDefinition[] | undefined;
|
|
529
|
+
/**
|
|
530
|
+
* Whether an action handler has been registered.
|
|
531
|
+
* @defaultValue `false`
|
|
532
|
+
*/
|
|
533
|
+
readonly hasAction?: boolean | undefined;
|
|
534
|
+
/**
|
|
535
|
+
* Command-level interactive resolver.
|
|
536
|
+
* @defaultValue `undefined`
|
|
537
|
+
*/
|
|
538
|
+
readonly interactive?: ErasedInteractiveResolver | undefined;
|
|
539
|
+
/**
|
|
540
|
+
* Nested subcommand definitions or built schemas.
|
|
541
|
+
* @defaultValue `[]`
|
|
542
|
+
*/
|
|
543
|
+
readonly commands?: readonly (CommandDefinition | CommandSchema)[] | undefined;
|
|
509
544
|
}
|
|
510
545
|
/**
|
|
511
|
-
*
|
|
546
|
+
* Create a {@link CommandSchema} from a plain definition object.
|
|
547
|
+
*
|
|
548
|
+
* Most consumers should prefer {@link command | command()}, which returns a
|
|
549
|
+
* {@link CommandBuilder} with type inference. `createCommandSchema()` is the
|
|
550
|
+
* low-level escape hatch for tooling that composes schemas as data.
|
|
551
|
+
*
|
|
552
|
+
* Flags, args, and subcommands are normalized recursively, so an already-built
|
|
553
|
+
* schema fed back in produces a deep-equal schema.
|
|
554
|
+
*
|
|
555
|
+
* Flag spellings are checked across the whole tree, so a definition whose names,
|
|
556
|
+
* aliases, or negated spellings collide with each other or with a propagated
|
|
557
|
+
* ancestor flag is rejected here. Both flags still parse under their canonical
|
|
558
|
+
* names, so what a collision costs is the shared spelling. Help advertises it on
|
|
559
|
+
* both flags and the parser answers it with one of them.
|
|
560
|
+
* Args go through the same invariants {@link CommandBuilder.arg} enforces.
|
|
561
|
+
* These are the checks the {@link CommandBuilder} applies as flags, args, and
|
|
562
|
+
* subcommands are registered.
|
|
563
|
+
*
|
|
564
|
+
* @param definition - Command name plus optional flags, args, and subcommands.
|
|
565
|
+
* @returns A fully populated {@link CommandSchema}.
|
|
566
|
+
* @throws {CLIError} With code `'INVALID_SCHEMA'` when a name at any depth is
|
|
567
|
+
* empty or contains whitespace, a flag or arg at any depth is named
|
|
568
|
+
* `__proto__`, which JavaScript cannot carry as a plain record key, or a flag
|
|
569
|
+
* record at any depth has a
|
|
570
|
+
* replaced prototype, which hides the entries a name check would read.
|
|
571
|
+
* @throws {CLIError} With code `'FLAG_NAME_COLLISION'` when two flags on one
|
|
572
|
+
* command share a spelling.
|
|
573
|
+
* @throws {CLIError} With code `'PROPAGATED_FLAG_COLLISION'` when a flag shadows
|
|
574
|
+
* a spelling propagated from an ancestor command.
|
|
575
|
+
* @throws {CLIError} With code `'INVALID_BUILDER_STATE'` when a positional comes
|
|
576
|
+
* after a variadic one, or `'DUPLICATE_STDIN_INPUT'` when two inputs on one
|
|
577
|
+
* command consume stdin and either is exclusive.
|
|
578
|
+
*
|
|
579
|
+
* @example
|
|
580
|
+
* ```ts
|
|
581
|
+
* const schema = createCommandSchema({
|
|
582
|
+
* name: 'deploy',
|
|
583
|
+
* description: 'Ship the build',
|
|
584
|
+
* flags: { force: { kind: 'boolean' } },
|
|
585
|
+
* args: [{ name: 'target', schema: { kind: 'string' } }],
|
|
586
|
+
* });
|
|
587
|
+
* ```
|
|
588
|
+
*/
|
|
589
|
+
declare function createCommandSchema(definition: CommandDefinition): CommandSchema;
|
|
590
|
+
/**
|
|
591
|
+
* Structural subset of {@linkcode CommandBuilder} accepted by `runCommand()`.
|
|
512
592
|
*
|
|
513
593
|
* Avoids generic type parameters so any `CommandBuilder<F, A, C>` satisfies
|
|
514
594
|
* this interface structurally — no variance constraints, no inference needed.
|
|
515
|
-
*
|
|
516
|
-
*
|
|
595
|
+
* The testkit reads `handler` and `_executionSteps` off it and hands them to
|
|
596
|
+
* the shared executor, so TypeScript never has to resolve
|
|
597
|
+
* {@linkcode CommandBuilder}'s full generic signature.
|
|
517
598
|
*
|
|
518
|
-
* @internal
|
|
519
599
|
*/
|
|
520
600
|
interface RunnableCommand {
|
|
521
601
|
readonly schema: CommandSchema;
|
|
@@ -529,10 +609,9 @@ interface RunnableCommand {
|
|
|
529
609
|
* custom tooling that mirrors the framework's type-erasure boundary.
|
|
530
610
|
*
|
|
531
611
|
* Uses widest possible generic bounds so any `CommandBuilder<F, A, C>` is
|
|
532
|
-
* assignable. The CLI layer's `
|
|
533
|
-
* the execution
|
|
612
|
+
* assignable. The CLI layer's `compileCommand()` traverses these to build
|
|
613
|
+
* the execution graph.
|
|
534
614
|
*
|
|
535
|
-
* @internal
|
|
536
615
|
*/
|
|
537
616
|
type AnyCommandBuilder = CommandBuilder<Record<string, FlagBuilder<FlagConfig>>, Record<string, ArgBuilder<ArgConfig>>, Record<string, unknown>>;
|
|
538
617
|
/**
|
|
@@ -562,32 +641,6 @@ type AnyCommandBuilder = CommandBuilder<Record<string, FlagBuilder<FlagConfig>>,
|
|
|
562
641
|
* ```
|
|
563
642
|
*/
|
|
564
643
|
declare class CommandBuilder<F extends Record<string, FlagBuilder<FlagConfig>> = {}, A extends Record<string, ArgBuilder<ArgConfig>> = {}, C extends Record<string, unknown> = Record<string, never>> {
|
|
565
|
-
/** @internal Runtime schema descriptor. */
|
|
566
|
-
readonly schema: CommandSchema;
|
|
567
|
-
/** @internal The action handler, if registered (type-erased for covariance). */
|
|
568
|
-
readonly handler: ErasedActionHandler | undefined;
|
|
569
|
-
/**
|
|
570
|
-
* @internal Nested sub-command builders (type-erased for heterogeneous storage).
|
|
571
|
-
*
|
|
572
|
-
* Stored separately from `schema.commands` because builders carry action
|
|
573
|
-
* handlers and phantom types needed by `eraseCommand()` in the CLI layer.
|
|
574
|
-
* `schema.commands` holds pure `CommandSchema[]` for help/completion.
|
|
575
|
-
*/
|
|
576
|
-
readonly _subcommands: readonly AnyCommandBuilder[];
|
|
577
|
-
/**
|
|
578
|
-
* @internal Execution steps in registration order.
|
|
579
|
-
*
|
|
580
|
-
* Distinct from `schema.middleware`: middleware handlers remain in schema
|
|
581
|
-
* for backward compatibility, while derives stay command-local and builder-
|
|
582
|
-
* scoped so future shared/global middleware can compose cleanly.
|
|
583
|
-
*/
|
|
584
|
-
readonly _executionSteps: readonly ExecutionStep[];
|
|
585
|
-
/** @internal Phantom brand for accumulated flag builder types. No runtime value. */
|
|
586
|
-
readonly _flags: F;
|
|
587
|
-
/** @internal Phantom brand for accumulated arg builder types. No runtime value. */
|
|
588
|
-
readonly _args: A;
|
|
589
|
-
/** @internal Phantom brand for accumulated context type. No runtime value. */
|
|
590
|
-
readonly _ctx: C;
|
|
591
644
|
/**
|
|
592
645
|
* Create a command builder from a pre-built schema descriptor.
|
|
593
646
|
*
|
|
@@ -870,6 +923,13 @@ declare class CommandBuilder<F extends Record<string, FlagBuilder<FlagConfig>> =
|
|
|
870
923
|
* ```
|
|
871
924
|
*
|
|
872
925
|
* @returns The builder (for chaining).
|
|
926
|
+
* @throws {@link CLIError} `INVALID_SCHEMA` when the name is `__proto__`,
|
|
927
|
+
* which a plain record cannot carry.
|
|
928
|
+
* @throws {@link CLIError} `FLAG_NAME_COLLISION` when the command already
|
|
929
|
+
* declares this name, or the new flag's spellings collide with another
|
|
930
|
+
* flag's.
|
|
931
|
+
* @throws {@link CLIError} `PROPAGATED_FLAG_COLLISION` when a spelling
|
|
932
|
+
* collides with one propagated to a registered subcommand.
|
|
873
933
|
*/
|
|
874
934
|
flag<N extends string, B extends FlagBuilder<FlagConfig>>(name: N & Exclude<N, keyof F>, builder: B): CommandBuilder<F & Record<N, B>, A, C>;
|
|
875
935
|
/**
|
|
@@ -910,13 +970,19 @@ declare class CommandBuilder<F extends Record<string, FlagBuilder<FlagConfig>> =
|
|
|
910
970
|
* ```
|
|
911
971
|
*
|
|
912
972
|
* @returns The builder (for chaining).
|
|
973
|
+
* @throws {@link CLIError} `INVALID_SCHEMA` when the name is `__proto__`,
|
|
974
|
+
* which a plain record cannot carry.
|
|
975
|
+
* @throws {@link CLIError} `INVALID_BUILDER_STATE` when an earlier arg on this
|
|
976
|
+
* command is variadic, so this one could never be filled.
|
|
977
|
+
* @throws {@link CLIError} `DUPLICATE_STDIN_INPUT` when another input on this
|
|
978
|
+
* command already consumes stdin exclusively.
|
|
913
979
|
*/
|
|
914
980
|
arg<N extends string, B extends ArgBuilder<ArgConfig>>(name: N & Exclude<N, keyof A>, builder: B): CommandBuilder<F, A & Record<N, B>, C>;
|
|
915
981
|
/**
|
|
916
982
|
* Register a nested subcommand on this command.
|
|
917
983
|
*
|
|
918
984
|
* The subcommand's builder is stored in `_subcommands` for the CLI layer's
|
|
919
|
-
* `
|
|
985
|
+
* `compileCommand()` to traverse when building the execution graph. The
|
|
920
986
|
* subcommand's `CommandSchema` is also appended to `schema.commands` for
|
|
921
987
|
* help rendering and completion generation.
|
|
922
988
|
*
|
|
@@ -934,6 +1000,9 @@ declare class CommandBuilder<F extends Record<string, FlagBuilder<FlagConfig>> =
|
|
|
934
1000
|
*
|
|
935
1001
|
* @param sub - Child {@link CommandBuilder} to nest under this command.
|
|
936
1002
|
* @returns The builder (for chaining).
|
|
1003
|
+
* @throws {@link CLIError} `PROPAGATED_FLAG_COLLISION` when a spelling this
|
|
1004
|
+
* command propagates collides with one the subcommand, or any of its own
|
|
1005
|
+
* descendants, declares.
|
|
937
1006
|
*/
|
|
938
1007
|
command<F2 extends Record<string, FlagBuilder<FlagConfig>>, A2 extends Record<string, ArgBuilder<ArgConfig>>, C2 extends Record<string, unknown>>(sub: CommandBuilder<F2, A2, C2>): CommandBuilder<F, A, C>;
|
|
939
1008
|
/**
|
|
@@ -1029,4 +1098,4 @@ declare function command(name: string): CommandBuilder;
|
|
|
1029
1098
|
*/
|
|
1030
1099
|
declare function group(name: string): CommandBuilder;
|
|
1031
1100
|
//#endregion
|
|
1032
|
-
export { type ActionHandler, type ActionParams, type AnyCommandBuilder, type CommandArgEntry, CommandBuilder, type
|
|
1101
|
+
export { type ActionHandler, type ActionParams, type AnyCommandBuilder, type CommandArgEntry, type CommandArgEntryDefinition, CommandBuilder, type CommandDefinition, type CommandExample, type CommandMeta, type CommandSchema, type DeriveHandler, type DeriveParams, type ErasedActionHandler, type ErasedDeriveHandler, type ErasedInputSources, type ErasedInteractiveResolver, type ExampleCommand, type ExampleMeta, type ExecutionStep, type InteractiveParams, type InteractiveResolver, type InteractiveResult, type Out, type RunnableCommand, type WidenContext, type WidenDerivedContext, command, createCommandSchema, group, resolveExampleCommand };
|