@kjanat/dreamcli 1.0.0 → 2.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/CHANGELOG.md +45 -6
- package/LICENSE +1 -1
- package/README.md +296 -164
- package/dist/core/cli/dispatch.d.mts +85 -0
- package/dist/core/cli/dispatch.mjs +1 -0
- package/dist/core/cli/index.d.mts +418 -0
- package/dist/core/cli/index.mjs +1 -0
- package/dist/core/cli/planner.d.mts +143 -0
- package/dist/core/cli/planner.mjs +1 -0
- package/dist/core/cli/plugin.d.mts +94 -0
- package/dist/core/cli/plugin.mjs +1 -0
- package/dist/core/cli/propagate.d.mts +39 -0
- package/dist/core/cli/propagate.mjs +1 -0
- package/dist/core/cli/root-help.d.mts +28 -0
- package/dist/core/cli/root-help.mjs +7 -0
- package/dist/core/cli/root-surface.d.mts +42 -0
- package/dist/core/cli/root-surface.mjs +1 -0
- package/dist/core/cli/runtime-preflight.d.mts +149 -0
- package/dist/core/cli/runtime-preflight.mjs +1 -0
- package/dist/core/completion/index.d.mts +46 -0
- package/dist/core/completion/index.mjs +1 -0
- package/dist/core/completion/shells/bash.d.mts +24 -0
- package/dist/core/completion/shells/bash.mjs +3 -0
- package/dist/core/completion/shells/fish.d.mts +20 -0
- package/dist/core/completion/shells/fish.mjs +2 -0
- package/dist/core/completion/shells/powershell.d.mts +14 -0
- package/dist/core/completion/shells/powershell.mjs +2 -0
- package/dist/core/completion/shells/shared.d.mts +139 -0
- package/dist/core/completion/shells/shared.mjs +1 -0
- package/dist/core/completion/shells/zsh.d.mts +24 -0
- package/dist/core/completion/shells/zsh.mjs +2 -0
- package/dist/core/config/index.d.mts +161 -0
- package/dist/core/config/index.mjs +1 -0
- package/dist/core/config/package-json.d.mts +68 -0
- package/dist/core/config/package-json.mjs +1 -0
- package/dist/core/errors/index.d.mts +126 -0
- package/dist/core/errors/index.mjs +1 -0
- package/dist/core/execution/index.d.mts +49 -0
- package/dist/core/execution/index.mjs +1 -0
- package/dist/core/help/index.d.mts +49 -0
- package/dist/core/help/index.mjs +8 -0
- package/dist/core/json-schema/index.d.mts +109 -0
- package/dist/core/json-schema/index.mjs +55 -0
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +185 -0
- package/dist/core/json-schema/meta-descriptions.generated.mjs +28 -0
- package/dist/core/output/activity.d.mts +194 -0
- package/dist/core/output/activity.mjs +1 -0
- package/dist/core/output/contracts.d.mts +88 -0
- package/dist/core/output/contracts.mjs +1 -0
- package/dist/core/output/display-value.d.mts +19 -0
- package/dist/core/output/display-value.mjs +1 -0
- package/dist/core/output/index.d.mts +280 -0
- package/dist/core/output/index.mjs +2 -0
- package/dist/core/output/renderers.d.mts +46 -0
- package/dist/core/output/renderers.mjs +1 -0
- package/dist/core/output/writer.d.mts +40 -0
- package/dist/core/output/writer.mjs +1 -0
- package/dist/core/parse/index.d.mts +79 -0
- package/dist/core/parse/index.mjs +1 -0
- package/dist/core/prompt/index.d.mts +205 -0
- package/dist/core/prompt/index.mjs +6 -0
- package/dist/core/resolve/args.d.mts +8 -0
- package/dist/core/resolve/args.mjs +1 -0
- package/dist/core/resolve/coerce.d.mts +22 -0
- package/dist/core/resolve/coerce.mjs +1 -0
- package/dist/core/resolve/config.d.mts +10 -0
- package/dist/core/resolve/config.mjs +1 -0
- package/dist/core/resolve/contracts.d.mts +112 -0
- package/dist/core/resolve/errors.d.mts +11 -0
- package/dist/core/resolve/errors.mjs +2 -0
- package/dist/core/resolve/flags.d.mts +10 -0
- package/dist/core/resolve/flags.mjs +1 -0
- package/dist/core/resolve/index.d.mts +42 -0
- package/dist/core/resolve/index.mjs +1 -0
- package/dist/core/resolve/property.d.mts +47 -0
- package/dist/core/resolve/property.mjs +1 -0
- package/dist/core/schema/activity.d.mts +169 -0
- package/dist/core/schema/arg.d.mts +559 -0
- package/dist/core/schema/arg.mjs +1 -0
- package/dist/core/schema/command.d.mts +960 -0
- package/dist/core/schema/command.mjs +1 -0
- package/dist/core/schema/flag.d.mts +491 -0
- package/dist/core/schema/flag.mjs +1 -0
- package/dist/core/schema/index.d.mts +8 -0
- package/dist/core/schema/middleware.d.mts +122 -0
- package/dist/core/schema/middleware.mjs +1 -0
- package/dist/core/schema/prompt.d.mts +117 -0
- package/dist/core/schema/run.d.mts +171 -0
- package/dist/core/schema-dsl/runtime.d.mts +144 -0
- package/dist/core/schema-dsl/runtime.mjs +2 -0
- package/dist/core/schema-dsl/to-json-schema.d.mts +30 -0
- package/dist/core/schema-dsl/to-json-schema.mjs +1 -0
- package/dist/core/testkit/index.d.mts +54 -0
- package/dist/core/testkit/index.mjs +1 -0
- package/dist/index.d.mts +28 -920
- package/dist/index.mjs +1 -10
- package/dist/runtime/adapter.d.mts +212 -0
- package/dist/{adapter-B37d9oia.mjs → runtime/adapter.mjs} +1 -1
- package/dist/runtime/auto.d.mts +26 -0
- package/dist/runtime/auto.mjs +1 -0
- package/dist/runtime/bun.d.mts +28 -0
- package/dist/runtime/bun.mjs +1 -0
- package/dist/runtime/deno.d.mts +76 -0
- package/dist/runtime/deno.mjs +2 -0
- package/dist/runtime/detect.d.mts +86 -0
- package/dist/runtime/detect.mjs +1 -0
- package/dist/runtime/index.d.mts +7 -0
- package/dist/runtime/node.d.mts +65 -0
- package/dist/runtime/node.mjs +2 -0
- package/dist/runtime/paths.d.mts +31 -0
- package/dist/runtime/paths.mjs +1 -0
- package/dist/runtime/support.d.mts +42 -0
- package/dist/runtime/support.mjs +1 -0
- package/dist/runtime.d.mts +6 -252
- package/dist/runtime.mjs +1 -1
- package/dist/testkit.d.mts +5 -24
- package/dist/testkit.mjs +1 -1
- package/dist/version.d.mts +16 -0
- package/dist/version.mjs +1 -0
- package/dreamcli.schema.json +338 -0
- package/examples/basic.ts +2 -2
- package/examples/gh/package.json +7 -11
- package/examples/gh/src/commands/auth.ts +2 -2
- package/examples/gh/src/commands/issue.ts +4 -4
- package/examples/gh/src/commands/pr.ts +4 -4
- package/examples/gh/src/docs.ts +11 -0
- package/examples/gh/src/lib/auth.ts +1 -1
- package/examples/gh/src/main.test.ts +6 -5
- package/examples/gh/src/main.ts +8 -6
- package/examples/interactive.ts +3 -3
- package/examples/json-mode.ts +4 -6
- package/examples/middleware.ts +3 -3
- package/examples/multi-command.ts +3 -3
- package/examples/spinner-progress.ts +5 -5
- package/examples/testing.ts +8 -6
- package/package.json +70 -44
- package/src/core/cli/dispatch.ts +4 -0
- package/src/core/cli/index.ts +185 -632
- package/src/core/cli/planner.ts +413 -0
- package/src/core/cli/plugin.ts +7 -1
- package/src/core/cli/propagate.ts +1 -1
- package/src/core/cli/runtime-preflight.ts +409 -0
- package/src/core/completion/index.ts +15 -9
- package/src/core/completion/shells/bash.ts +6 -3
- package/src/core/completion/shells/fish.ts +245 -10
- package/src/core/completion/shells/powershell.ts +390 -9
- package/src/core/completion/shells/shared.ts +4 -4
- package/src/core/completion/shells/zsh.ts +12 -7
- package/src/core/config/index.ts +7 -4
- package/src/core/config/package-json.ts +6 -2
- package/src/core/errors/index.ts +23 -8
- package/src/core/execution/index.ts +270 -0
- package/src/core/help/index.ts +13 -15
- package/src/core/json-schema/index.ts +193 -7
- package/src/core/json-schema/meta-descriptions.generated.ts +202 -0
- package/src/core/output/contracts.ts +194 -0
- package/src/core/output/index.ts +47 -82
- package/src/core/output/renderers.ts +125 -0
- package/src/core/parse/index.ts +39 -21
- package/src/core/prompt/index.ts +44 -27
- package/src/core/resolve/args.ts +144 -0
- package/src/core/resolve/coerce.ts +432 -0
- package/src/core/resolve/config.ts +26 -0
- package/src/core/resolve/contracts.ts +135 -0
- package/src/core/resolve/errors.ts +227 -0
- package/src/core/resolve/flags.ts +205 -0
- package/src/core/resolve/index.ts +41 -1264
- package/src/core/resolve/property.ts +99 -0
- package/src/core/schema/activity.ts +3 -0
- package/src/core/schema/arg.ts +26 -14
- package/src/core/schema/command.ts +265 -38
- package/src/core/schema/flag.ts +120 -15
- package/src/core/schema/index.ts +11 -2
- package/src/core/schema/middleware.ts +6 -6
- package/src/core/schema/prompt.ts +9 -1
- package/src/core/schema/run.ts +25 -17
- package/src/core/schema-dsl/index.ts +109 -0
- package/src/core/schema-dsl/parse.ts +262 -0
- package/src/core/schema-dsl/runtime.ts +609 -0
- package/src/core/schema-dsl/to-json-schema.ts +102 -0
- package/src/core/testkit/index.ts +55 -297
- package/src/index.ts +10 -4
- package/src/runtime/adapter.ts +13 -10
- package/src/runtime/auto.ts +3 -3
- package/src/runtime/bun.ts +4 -4
- package/src/runtime/deno.ts +43 -29
- package/src/runtime/detect.ts +4 -1
- package/src/runtime/index.ts +1 -1
- package/src/runtime/node.ts +43 -21
- package/src/runtime/paths.ts +9 -3
- package/src/runtime/support.ts +20 -4
- package/src/runtime.ts +1 -1
- package/src/testkit.ts +10 -8
- package/dist/adapter-CCSh5juX.cjs +0 -1
- package/dist/adapter-DIwO-q7K.d.mts +0 -3447
- package/dist/adapter-DQnxxLiE.d.cts +0 -3447
- package/dist/auto-5cjZaF9V.mjs +0 -3
- package/dist/auto-B0eSgoDw.cjs +0 -3
- package/dist/index.cjs +0 -10
- package/dist/index.d.cts +0 -920
- package/dist/runtime.cjs +0 -1
- package/dist/runtime.d.cts +0 -253
- package/dist/testkit-CEDYPvhF.mjs +0 -14
- package/dist/testkit-ClIKijxC.cjs +0 -14
- package/dist/testkit.cjs +0 -1
- package/dist/testkit.d.cts +0 -25
- package/examples/gh/tsconfig.json +0 -37
- package/examples/tsconfig.json +0 -17
- package/src/core/cli/AGENTS.md +0 -72
- package/src/core/completion/AGENTS.md +0 -72
- package/src/core/completion/completion-test-helpers.ts +0 -48
- package/src/core/output/AGENTS.md +0 -69
- package/src/core/resolve/AGENTS.md +0 -69
- package/src/core/schema/AGENTS.md +0 -61
- package/src/core/testkit/AGENTS.md +0 -55
- package/src/runtime/AGENTS.md +0 -74
- package/src/runtime/test-helpers.ts +0 -40
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Command schema builder with flag/arg composition and type accumulation.
|
|
3
3
|
*
|
|
4
|
-
* The
|
|
5
|
-
* parameters track accumulated flag and arg builder types. Chaining
|
|
6
|
-
* and `.arg()` calls produces progressively narrower types. The
|
|
7
|
-
* handler receives fully typed `{ args, flags, ctx, out }`.
|
|
4
|
+
* The {@linkcode command} factory returns an immutable {@linkcode CommandBuilder}
|
|
5
|
+
* whose generic parameters track accumulated flag and arg builder types. Chaining
|
|
6
|
+
* `.flag()` and `.arg()` calls produces progressively narrower types. The
|
|
7
|
+
* `.action()` handler receives fully typed `{ args, flags, ctx, out, meta }`.
|
|
8
8
|
*
|
|
9
9
|
* @module dreamcli/core/schema/command
|
|
10
10
|
*/
|
|
@@ -58,7 +58,9 @@ type WidenDerivedContext<C extends Record<string, unknown>, Output> =
|
|
|
58
58
|
* Both start empty (`{}`) and grow as `.flag()` / `.arg()` are called.
|
|
59
59
|
*/
|
|
60
60
|
interface CommandConfig {
|
|
61
|
+
/** Accumulated flag builders keyed by flag name. */
|
|
61
62
|
readonly flags: Record<string, FlagBuilder<FlagConfig>>;
|
|
63
|
+
/** Accumulated arg builders keyed by arg name. */
|
|
62
64
|
readonly args: Record<string, ArgBuilder<ArgConfig>>;
|
|
63
65
|
}
|
|
64
66
|
|
|
@@ -97,6 +99,8 @@ type InteractiveResult = Readonly<Record<string, PromptConfig | false | undefine
|
|
|
97
99
|
*
|
|
98
100
|
* @example
|
|
99
101
|
* ```ts
|
|
102
|
+
* import { command, flag } from '@kjanat/dreamcli';
|
|
103
|
+
*
|
|
100
104
|
* const deploy = command('deploy')
|
|
101
105
|
* .flag('region', flag.enum(['us', 'eu', 'ap']))
|
|
102
106
|
* .interactive(({ flags }) => ({
|
|
@@ -105,7 +109,9 @@ type InteractiveResult = Readonly<Record<string, PromptConfig | false | undefine
|
|
|
105
109
|
* message: 'Select region',
|
|
106
110
|
* },
|
|
107
111
|
* }))
|
|
108
|
-
* .action(({ flags }) => {
|
|
112
|
+
* .action(({ flags, out }) => {
|
|
113
|
+
* out.log(`Deploying to ${flags.region}`);
|
|
114
|
+
* });
|
|
109
115
|
* ```
|
|
110
116
|
*/
|
|
111
117
|
type InteractiveResolver<F extends Record<string, FlagBuilder<FlagConfig>>> = (
|
|
@@ -113,10 +119,10 @@ type InteractiveResolver<F extends Record<string, FlagBuilder<FlagConfig>>> = (
|
|
|
113
119
|
) => InteractiveResult;
|
|
114
120
|
|
|
115
121
|
/**
|
|
116
|
-
* Type-erased interactive resolver stored on
|
|
122
|
+
* Type-erased interactive resolver stored on {@linkcode CommandSchema}.
|
|
117
123
|
*
|
|
118
124
|
* Advanced bridge type: most consumers should use {@link InteractiveResolver}
|
|
119
|
-
* via
|
|
125
|
+
* via {@linkcode command | command().interactive()} and never reference this alias directly.
|
|
120
126
|
*
|
|
121
127
|
* At runtime, the resolver receives `{ flags: Record<string, unknown> }`
|
|
122
128
|
* and returns `Record<string, PromptConfig | falsy>`. The phantom types
|
|
@@ -244,7 +250,7 @@ interface Out {
|
|
|
244
250
|
* handle is active, or when the handle was already stopped.
|
|
245
251
|
*
|
|
246
252
|
* The framework calls this automatically in `runCommand()` and
|
|
247
|
-
* `cli.run()`. Direct users of `createOutput()` should call it
|
|
253
|
+
* `cli().run()`. Direct users of `createOutput()` should call it
|
|
248
254
|
* themselves after the handler returns or throws.
|
|
249
255
|
*
|
|
250
256
|
* @example
|
|
@@ -297,10 +303,15 @@ interface ActionParams<
|
|
|
297
303
|
A extends Record<string, ArgBuilder<ArgConfig>>,
|
|
298
304
|
C extends Record<string, unknown> = Record<string, never>,
|
|
299
305
|
> {
|
|
306
|
+
/** Fully resolved positional argument values, typed from `.arg()` definitions. */
|
|
300
307
|
readonly args: Readonly<InferArgs<A>>;
|
|
308
|
+
/** Fully resolved flag values, typed from `.flag()` definitions. */
|
|
301
309
|
readonly flags: Readonly<InferFlags<F>>;
|
|
310
|
+
/** Middleware/derive-provided context, typed from `.middleware()` and `.derive()` chains. */
|
|
302
311
|
readonly ctx: Readonly<C>;
|
|
312
|
+
/** Structured output channel for stdout, stderr, JSON, tables, and spinners. */
|
|
303
313
|
readonly out: Out;
|
|
314
|
+
/** Runtime metadata about the CLI program and current command. */
|
|
304
315
|
readonly meta: CommandMeta;
|
|
305
316
|
}
|
|
306
317
|
|
|
@@ -317,6 +328,28 @@ type ActionHandler<
|
|
|
317
328
|
C extends Record<string, unknown> = Record<string, never>,
|
|
318
329
|
> = (params: ActionParams<F, A, C>) => void | Promise<void>;
|
|
319
330
|
|
|
331
|
+
/**
|
|
332
|
+
* Type-erased action handler stored on {@linkcode CommandBuilder}.
|
|
333
|
+
*
|
|
334
|
+
* The typed {@linkcode ActionHandler} from `.action()` is cast to this
|
|
335
|
+
* erased form at the type-erasure boundary, keeping {@linkcode CommandBuilder}
|
|
336
|
+
* covariant in its generic parameters. This enables structural
|
|
337
|
+
* compatibility across TypeScript declaration-file boundaries where
|
|
338
|
+
* generic inference may fall back to constraint types.
|
|
339
|
+
*
|
|
340
|
+
* Follows the same erasure pattern as {@link ErasedDeriveHandler} and
|
|
341
|
+
* {@link ErasedMiddlewareHandler}.
|
|
342
|
+
*
|
|
343
|
+
* @internal
|
|
344
|
+
*/
|
|
345
|
+
type ErasedActionHandler = (params: {
|
|
346
|
+
readonly args: Readonly<Record<string, unknown>>;
|
|
347
|
+
readonly flags: Readonly<Record<string, unknown>>;
|
|
348
|
+
readonly ctx: Readonly<Record<string, unknown>>;
|
|
349
|
+
readonly out: Out;
|
|
350
|
+
readonly meta: CommandMeta;
|
|
351
|
+
}) => void | Promise<void>;
|
|
352
|
+
|
|
320
353
|
/**
|
|
321
354
|
* The bag of values received by a derive handler.
|
|
322
355
|
*
|
|
@@ -334,11 +367,11 @@ type DeriveParams<
|
|
|
334
367
|
* Command-scoped typed pre-action handler.
|
|
335
368
|
*
|
|
336
369
|
* Derive handlers may:
|
|
337
|
-
* - validate resolved input and throw
|
|
370
|
+
* - validate resolved input and throw {@linkcode CLIError}
|
|
338
371
|
* - return `undefined` to continue without changing context
|
|
339
372
|
* - return an object whose properties merge into `ctx` downstream
|
|
340
373
|
*
|
|
341
|
-
* They cannot wrap downstream execution; use
|
|
374
|
+
* They cannot wrap downstream execution; use {@linkcode middleware} for that.
|
|
342
375
|
*/
|
|
343
376
|
type DeriveHandler<
|
|
344
377
|
F extends Record<string, FlagBuilder<FlagConfig>>,
|
|
@@ -365,7 +398,7 @@ type ErasedDeriveHandler = (params: {
|
|
|
365
398
|
|
|
366
399
|
/**
|
|
367
400
|
* Internal execution step union preserving registration order across
|
|
368
|
-
*
|
|
401
|
+
* {@linkcode CommandBuilder.derive | derive()} and {@linkcode CommandBuilder.middleware | middleware()}.
|
|
369
402
|
*
|
|
370
403
|
* @internal
|
|
371
404
|
*/
|
|
@@ -449,7 +482,9 @@ interface CommandSchema {
|
|
|
449
482
|
* The array ordering in {@link CommandSchema.args} determines CLI position.
|
|
450
483
|
*/
|
|
451
484
|
interface CommandArgEntry {
|
|
485
|
+
/** User-facing argument name (shown in help as `<name>`). */
|
|
452
486
|
readonly name: string;
|
|
487
|
+
/** Runtime descriptor controlling parsing, presence, and coercion. */
|
|
453
488
|
readonly schema: ArgSchema;
|
|
454
489
|
}
|
|
455
490
|
|
|
@@ -493,6 +528,156 @@ function validateArgEntry(name: string, schema: ArgSchema, args: readonly Comman
|
|
|
493
528
|
);
|
|
494
529
|
}
|
|
495
530
|
|
|
531
|
+
// --- Flag collision validation
|
|
532
|
+
|
|
533
|
+
type FlagFormKind = 'canonical' | 'alias';
|
|
534
|
+
|
|
535
|
+
interface FlagForm {
|
|
536
|
+
readonly owner: string;
|
|
537
|
+
readonly name: string;
|
|
538
|
+
readonly kind: FlagFormKind;
|
|
539
|
+
readonly hidden: boolean;
|
|
540
|
+
}
|
|
541
|
+
|
|
542
|
+
function formatFlagToken(name: string, kind: FlagFormKind): string {
|
|
543
|
+
return kind === 'alias' && name.length === 1 ? `-${name}` : `--${name}`;
|
|
544
|
+
}
|
|
545
|
+
|
|
546
|
+
function describeFlagForm(form: FlagForm): string {
|
|
547
|
+
if (form.kind === 'canonical') {
|
|
548
|
+
return `canonical flag ${formatFlagToken(form.name, form.kind)}`;
|
|
549
|
+
}
|
|
550
|
+
|
|
551
|
+
const aliasType = form.name.length === 1 ? 'short alias' : 'long alias';
|
|
552
|
+
return `${form.hidden ? 'hidden ' : ''}${aliasType} ${formatFlagToken(form.name, form.kind)}`;
|
|
553
|
+
}
|
|
554
|
+
|
|
555
|
+
function listFlagForms(name: string, schema: FlagSchema): readonly FlagForm[] {
|
|
556
|
+
return [
|
|
557
|
+
{
|
|
558
|
+
owner: name,
|
|
559
|
+
name,
|
|
560
|
+
kind: 'canonical',
|
|
561
|
+
hidden: false,
|
|
562
|
+
},
|
|
563
|
+
...schema.aliases.map((alias) => ({
|
|
564
|
+
owner: name,
|
|
565
|
+
name: alias.name,
|
|
566
|
+
kind: 'alias' as const,
|
|
567
|
+
hidden: alias.hidden,
|
|
568
|
+
})),
|
|
569
|
+
];
|
|
570
|
+
}
|
|
571
|
+
|
|
572
|
+
function throwFlagCollisionError(
|
|
573
|
+
commandName: string,
|
|
574
|
+
form: FlagForm,
|
|
575
|
+
existing: FlagForm,
|
|
576
|
+
options?: { inherited?: boolean },
|
|
577
|
+
): never {
|
|
578
|
+
const inherited = options?.inherited ?? false;
|
|
579
|
+
const existingOwner = `flag ${formatFlagToken(existing.owner, 'canonical')}`;
|
|
580
|
+
const subject = `Command '${commandName}' ${existingOwner}`;
|
|
581
|
+
|
|
582
|
+
throw new CLIError(
|
|
583
|
+
inherited
|
|
584
|
+
? `${subject} propagates ${describeFlagForm(existing)}, which collides with ${describeFlagForm(form)} on flag ${formatFlagToken(form.owner, 'canonical')}`
|
|
585
|
+
: `Command '${commandName}' flag ${formatFlagToken(form.owner, 'canonical')} ${describeFlagForm(form)} collides with ${describeFlagForm(existing)} on ${existingOwner}`,
|
|
586
|
+
{
|
|
587
|
+
code: inherited ? 'PROPAGATED_FLAG_COLLISION' : 'FLAG_NAME_COLLISION',
|
|
588
|
+
details: {
|
|
589
|
+
command: commandName,
|
|
590
|
+
flag: form.owner,
|
|
591
|
+
surface: form.name,
|
|
592
|
+
surfaceKind: form.kind,
|
|
593
|
+
hidden: form.hidden,
|
|
594
|
+
existingFlag: existing.owner,
|
|
595
|
+
existingSurface: existing.name,
|
|
596
|
+
existingSurfaceKind: existing.kind,
|
|
597
|
+
existingHidden: existing.hidden,
|
|
598
|
+
inherited,
|
|
599
|
+
},
|
|
600
|
+
},
|
|
601
|
+
);
|
|
602
|
+
}
|
|
603
|
+
|
|
604
|
+
function validateLocalFlagCollisions(
|
|
605
|
+
commandName: string,
|
|
606
|
+
flags: Readonly<Record<string, FlagSchema>>,
|
|
607
|
+
): void {
|
|
608
|
+
const seen = new Map<string, FlagForm>();
|
|
609
|
+
|
|
610
|
+
for (const [name, schema] of Object.entries(flags)) {
|
|
611
|
+
for (const form of listFlagForms(name, schema)) {
|
|
612
|
+
const existing = seen.get(form.name);
|
|
613
|
+
if (existing !== undefined) {
|
|
614
|
+
throwFlagCollisionError(commandName, form, existing);
|
|
615
|
+
}
|
|
616
|
+
seen.set(form.name, form);
|
|
617
|
+
}
|
|
618
|
+
}
|
|
619
|
+
}
|
|
620
|
+
|
|
621
|
+
function validateInheritedFlagCollisions(
|
|
622
|
+
commandName: string,
|
|
623
|
+
inherited: Readonly<Record<string, FlagSchema>>,
|
|
624
|
+
local: Readonly<Record<string, FlagSchema>>,
|
|
625
|
+
): void {
|
|
626
|
+
const inheritedForms = new Map<string, FlagForm>();
|
|
627
|
+
|
|
628
|
+
for (const [name, schema] of Object.entries(inherited)) {
|
|
629
|
+
for (const form of listFlagForms(name, schema)) {
|
|
630
|
+
inheritedForms.set(form.name, form);
|
|
631
|
+
}
|
|
632
|
+
}
|
|
633
|
+
|
|
634
|
+
for (const [name, schema] of Object.entries(local)) {
|
|
635
|
+
for (const form of listFlagForms(name, schema)) {
|
|
636
|
+
const existing = inheritedForms.get(form.name);
|
|
637
|
+
if (existing !== undefined) {
|
|
638
|
+
throwFlagCollisionError(commandName, form, existing, { inherited: true });
|
|
639
|
+
}
|
|
640
|
+
}
|
|
641
|
+
}
|
|
642
|
+
}
|
|
643
|
+
|
|
644
|
+
function buildInheritedFlagsForChildren(
|
|
645
|
+
inherited: Readonly<Record<string, FlagSchema>>,
|
|
646
|
+
local: Readonly<Record<string, FlagSchema>>,
|
|
647
|
+
): Readonly<Record<string, FlagSchema>> {
|
|
648
|
+
const next: Record<string, FlagSchema> = { ...inherited };
|
|
649
|
+
|
|
650
|
+
for (const name of Object.keys(local)) {
|
|
651
|
+
delete next[name];
|
|
652
|
+
}
|
|
653
|
+
|
|
654
|
+
for (const [name, schema] of Object.entries(local)) {
|
|
655
|
+
if (schema.propagate) {
|
|
656
|
+
next[name] = schema;
|
|
657
|
+
}
|
|
658
|
+
}
|
|
659
|
+
|
|
660
|
+
return next;
|
|
661
|
+
}
|
|
662
|
+
|
|
663
|
+
function validateCommandFlagTree(
|
|
664
|
+
command: CommandSchema,
|
|
665
|
+
inheritedFlags: Readonly<Record<string, FlagSchema>> = {},
|
|
666
|
+
): void {
|
|
667
|
+
validateLocalFlagCollisions(command.name, command.flags);
|
|
668
|
+
|
|
669
|
+
const visibleInherited: Record<string, FlagSchema> = { ...inheritedFlags };
|
|
670
|
+
for (const name of Object.keys(command.flags)) {
|
|
671
|
+
delete visibleInherited[name];
|
|
672
|
+
}
|
|
673
|
+
validateInheritedFlagCollisions(command.name, visibleInherited, command.flags);
|
|
674
|
+
|
|
675
|
+
const inheritedForChildren = buildInheritedFlagsForChildren(inheritedFlags, command.flags);
|
|
676
|
+
for (const child of command.commands) {
|
|
677
|
+
validateCommandFlagTree(child, inheritedForChildren);
|
|
678
|
+
}
|
|
679
|
+
}
|
|
680
|
+
|
|
496
681
|
// --- Type-erased command interface (shared between schema and CLI layers)
|
|
497
682
|
|
|
498
683
|
/**
|
|
@@ -506,11 +691,11 @@ function validateArgEntry(name: string, schema: ArgSchema, args: readonly Comman
|
|
|
506
691
|
* schema (for name/alias matching and help) and the ability to delegate to
|
|
507
692
|
* `runCommand()`. This interface captures exactly that contract.
|
|
508
693
|
*
|
|
509
|
-
* The `_execute` function closes over the original typed
|
|
694
|
+
* The `_execute` function closes over the original typed {@linkcode CommandBuilder},
|
|
510
695
|
* preserving full type safety inside the closure while presenting a
|
|
511
696
|
* uniform interface to the dispatcher.
|
|
512
697
|
*
|
|
513
|
-
* Defined here (rather than in the CLI layer) so both
|
|
698
|
+
* Defined here (rather than in the CLI layer) so both {@linkcode CommandBuilder} and
|
|
514
699
|
* `CLIBuilder` can reference it without circular imports.
|
|
515
700
|
*
|
|
516
701
|
* @internal
|
|
@@ -528,10 +713,28 @@ interface ErasedCommand {
|
|
|
528
713
|
* @internal
|
|
529
714
|
*/
|
|
530
715
|
readonly subcommands: ReadonlyMap<string, ErasedCommand>;
|
|
716
|
+
/** Original command builder captured at the type-erasure boundary. */
|
|
717
|
+
readonly _command?: AnyCommandBuilder;
|
|
531
718
|
/** Execute this command against argv. Closes over the typed CommandBuilder. */
|
|
532
719
|
readonly _execute: (argv: readonly string[], options?: RunOptions) => Promise<RunResult>;
|
|
533
720
|
}
|
|
534
721
|
|
|
722
|
+
/**
|
|
723
|
+
* Structural subset of {@linkcode CommandBuilder} consumed by the execution pipeline.
|
|
724
|
+
*
|
|
725
|
+
* Avoids generic type parameters so any `CommandBuilder<F, A, C>` satisfies
|
|
726
|
+
* this interface structurally — no variance constraints, no inference needed.
|
|
727
|
+
* Used by `runCommand()` and the shared executor to accept commands without
|
|
728
|
+
* requiring TypeScript to resolve {@linkcode CommandBuilder}'s full generic signature.
|
|
729
|
+
*
|
|
730
|
+
* @internal
|
|
731
|
+
*/
|
|
732
|
+
interface RunnableCommand {
|
|
733
|
+
readonly schema: CommandSchema;
|
|
734
|
+
readonly handler: ErasedActionHandler | undefined;
|
|
735
|
+
readonly _executionSteps: readonly ExecutionStep[];
|
|
736
|
+
}
|
|
737
|
+
|
|
535
738
|
// --- Type-erased builder alias (for heterogeneous subcommand storage)
|
|
536
739
|
|
|
537
740
|
/**
|
|
@@ -605,8 +808,8 @@ class CommandBuilder<
|
|
|
605
808
|
/** @internal Runtime schema descriptor. */
|
|
606
809
|
readonly schema: CommandSchema;
|
|
607
810
|
|
|
608
|
-
/** @internal The action handler, if registered. */
|
|
609
|
-
readonly handler:
|
|
811
|
+
/** @internal The action handler, if registered (type-erased for covariance). */
|
|
812
|
+
readonly handler: ErasedActionHandler | undefined;
|
|
610
813
|
|
|
611
814
|
/**
|
|
612
815
|
* @internal Nested sub-command builders (type-erased for heterogeneous storage).
|
|
@@ -626,15 +829,16 @@ class CommandBuilder<
|
|
|
626
829
|
*/
|
|
627
830
|
readonly _executionSteps: readonly ExecutionStep[];
|
|
628
831
|
|
|
629
|
-
/**
|
|
630
|
-
* @internal Type brands — exist only in the type system (`declare`
|
|
631
|
-
* produces no runtime property). Used for type inference.
|
|
632
|
-
*/
|
|
832
|
+
/** @internal Phantom brand for accumulated flag builder types. No runtime value. */
|
|
633
833
|
declare readonly _flags: F;
|
|
834
|
+
/** @internal Phantom brand for accumulated arg builder types. No runtime value. */
|
|
634
835
|
declare readonly _args: A;
|
|
836
|
+
/** @internal Phantom brand for accumulated context type. No runtime value. */
|
|
635
837
|
declare readonly _ctx: C;
|
|
636
838
|
|
|
637
839
|
/**
|
|
840
|
+
* Create a command builder from a pre-built schema descriptor.
|
|
841
|
+
*
|
|
638
842
|
* @param schema - Runtime command descriptor.
|
|
639
843
|
* @param handler - Action handler, if registered.
|
|
640
844
|
* @param subcommands - Nested sub-command builders (type-erased).
|
|
@@ -642,7 +846,7 @@ class CommandBuilder<
|
|
|
642
846
|
*/
|
|
643
847
|
constructor(
|
|
644
848
|
schema: CommandSchema,
|
|
645
|
-
handler?:
|
|
849
|
+
handler?: ErasedActionHandler,
|
|
646
850
|
subcommands?: readonly AnyCommandBuilder[],
|
|
647
851
|
executionSteps?: readonly ExecutionStep[],
|
|
648
852
|
) {
|
|
@@ -661,7 +865,7 @@ class CommandBuilder<
|
|
|
661
865
|
* resolved flag values. It returns a prompt schema for flags that need
|
|
662
866
|
* interactive input based on the current state.
|
|
663
867
|
*
|
|
664
|
-
* For flags the resolver returns a
|
|
868
|
+
* For flags the resolver returns a {@linkcode PromptConfig}, that config is used
|
|
665
869
|
* instead of any per-flag `.prompt()` config. For flags returned as falsy
|
|
666
870
|
* (or not mentioned), per-flag `.prompt()` configs are used as fallback.
|
|
667
871
|
*
|
|
@@ -710,7 +914,7 @@ class CommandBuilder<
|
|
|
710
914
|
* - return an object to merge additional properties into `ctx`
|
|
711
915
|
*
|
|
712
916
|
* Unlike middleware, derive cannot wrap downstream execution and does not
|
|
713
|
-
* use `next()`. Use
|
|
917
|
+
* use `next()`. Use {@linkcode middleware} for timing, logging, retries, cleanup,
|
|
714
918
|
* or error-boundary patterns.
|
|
715
919
|
*
|
|
716
920
|
* Adding derive drops the current handler (like `.flag()`, `.arg()`, and
|
|
@@ -761,7 +965,7 @@ class CommandBuilder<
|
|
|
761
965
|
* Register middleware to run before the action handler.
|
|
762
966
|
*
|
|
763
967
|
* Middleware executes in registration order. Each middleware receives
|
|
764
|
-
* `{ args, flags, ctx, out, next }` and must call `next(additions)`
|
|
968
|
+
* `{ args, flags, ctx, out, meta, next }` and must call `next(additions)`
|
|
765
969
|
* to continue the chain. Context additions are merged and become
|
|
766
970
|
* typed downstream.
|
|
767
971
|
*
|
|
@@ -771,7 +975,7 @@ class CommandBuilder<
|
|
|
771
975
|
*
|
|
772
976
|
* @example
|
|
773
977
|
* ```ts
|
|
774
|
-
* import { CLIError, command, middleware } from 'dreamcli';
|
|
978
|
+
* import { CLIError, command, middleware } from '@kjanat/dreamcli';
|
|
775
979
|
*
|
|
776
980
|
* interface User {
|
|
777
981
|
* id: string;
|
|
@@ -810,7 +1014,8 @@ class CommandBuilder<
|
|
|
810
1014
|
* });
|
|
811
1015
|
* ```
|
|
812
1016
|
*
|
|
813
|
-
* @param m - {@link Middleware} instance created via
|
|
1017
|
+
* @param m - {@link Middleware} instance created via {@linkcode middleware | middleware()}.
|
|
1018
|
+
* Middleware handlers receive `{ args, flags, ctx, out, meta, next }`.
|
|
814
1019
|
* @returns The builder (for chaining).
|
|
815
1020
|
*/
|
|
816
1021
|
middleware<Output extends Record<string, unknown>>(
|
|
@@ -979,8 +1184,8 @@ class CommandBuilder<
|
|
|
979
1184
|
* bindings, and description. See {@link FlagBuilder} for available modifiers.
|
|
980
1185
|
*
|
|
981
1186
|
* @param name - Flag name (used as `--name` on CLI and `flags.*` in handler).
|
|
982
|
-
* @param builder - Configured
|
|
983
|
-
* `flag.number()`, `flag.enum()`, `flag.array()`, or `flag.custom()`.
|
|
1187
|
+
* @param builder - Configured {@linkcode FlagBuilder} from {@linkcode flag | flag.string()},
|
|
1188
|
+
* `flag.boolean()`, `flag.number()`, `flag.enum()`, `flag.array()`, or `flag.custom()`.
|
|
984
1189
|
*
|
|
985
1190
|
* @example
|
|
986
1191
|
* ```ts
|
|
@@ -1014,9 +1219,18 @@ class CommandBuilder<
|
|
|
1014
1219
|
name: N & Exclude<N, keyof F>,
|
|
1015
1220
|
builder: B,
|
|
1016
1221
|
): CommandBuilder<F & Record<N, B>, A, C> {
|
|
1222
|
+
if (name in this.schema.flags) {
|
|
1223
|
+
throw new CLIError(`Command '${this.schema.name}' already defines flag --${name}`, {
|
|
1224
|
+
code: 'FLAG_NAME_COLLISION',
|
|
1225
|
+
details: { command: this.schema.name, flag: name, surface: name, surfaceKind: 'canonical' },
|
|
1226
|
+
});
|
|
1227
|
+
}
|
|
1228
|
+
|
|
1017
1229
|
const nextFlags = { ...this.schema.flags, [name]: builder.schema };
|
|
1230
|
+
const nextSchema = { ...this.schema, flags: nextFlags, hasAction: false };
|
|
1231
|
+
validateCommandFlagTree(nextSchema);
|
|
1018
1232
|
return new CommandBuilder(
|
|
1019
|
-
|
|
1233
|
+
nextSchema,
|
|
1020
1234
|
// handler is intentionally dropped — adding a flag invalidates
|
|
1021
1235
|
// the previous handler's type signature
|
|
1022
1236
|
undefined,
|
|
@@ -1039,7 +1253,7 @@ class CommandBuilder<
|
|
|
1039
1253
|
* description. See {@link ArgBuilder} for available modifiers.
|
|
1040
1254
|
*
|
|
1041
1255
|
* @param name - Positional arg name (used in help text and `args.*`).
|
|
1042
|
-
* @param builder - Configured
|
|
1256
|
+
* @param builder - Configured {@linkcode ArgBuilder} from `arg.string()`, `arg.number()`,
|
|
1043
1257
|
* or `arg.custom()`.
|
|
1044
1258
|
*
|
|
1045
1259
|
* @example
|
|
@@ -1113,11 +1327,13 @@ class CommandBuilder<
|
|
|
1113
1327
|
A2 extends Record<string, ArgBuilder<ArgConfig>>,
|
|
1114
1328
|
C2 extends Record<string, unknown>,
|
|
1115
1329
|
>(sub: CommandBuilder<F2, A2, C2>): CommandBuilder<F, A, C> {
|
|
1330
|
+
const nextSchema = {
|
|
1331
|
+
...this.schema,
|
|
1332
|
+
commands: [...this.schema.commands, sub.schema],
|
|
1333
|
+
};
|
|
1334
|
+
validateCommandFlagTree(nextSchema);
|
|
1116
1335
|
return new CommandBuilder(
|
|
1117
|
-
|
|
1118
|
-
...this.schema,
|
|
1119
|
-
commands: [...this.schema.commands, sub.schema],
|
|
1120
|
-
},
|
|
1336
|
+
nextSchema,
|
|
1121
1337
|
this.handler,
|
|
1122
1338
|
[...this._subcommands, eraseBuilder(sub)],
|
|
1123
1339
|
this._executionSteps,
|
|
@@ -1129,7 +1345,7 @@ class CommandBuilder<
|
|
|
1129
1345
|
/**
|
|
1130
1346
|
* Register the action handler for this command.
|
|
1131
1347
|
*
|
|
1132
|
-
* The handler receives fully typed `{ args, flags, ctx, out }` derived
|
|
1348
|
+
* The handler receives fully typed `{ args, flags, ctx, out, meta }` derived
|
|
1133
1349
|
* from the accumulated `.flag()`, `.arg()`, `.derive()`, and `.middleware()`
|
|
1134
1350
|
* definitions.
|
|
1135
1351
|
*
|
|
@@ -1139,38 +1355,43 @@ class CommandBuilder<
|
|
|
1139
1355
|
* @param handler - Function receiving `ActionParams<F, A, C>`.
|
|
1140
1356
|
*
|
|
1141
1357
|
* @example
|
|
1358
|
+
* ```ts
|
|
1142
1359
|
* // Minimal
|
|
1143
1360
|
* command('greet')
|
|
1144
1361
|
* .arg('name', arg.string())
|
|
1145
1362
|
* .action(({ args, out }) => {
|
|
1146
1363
|
* out.log(`Hello, ${args.name}!`);
|
|
1147
1364
|
* });
|
|
1365
|
+
* ```
|
|
1148
1366
|
*
|
|
1149
1367
|
* @example
|
|
1150
|
-
*
|
|
1368
|
+
* ```ts
|
|
1369
|
+
* // Full params — flags, args, context, output, metadata
|
|
1151
1370
|
* command('deploy')
|
|
1152
1371
|
* .arg('target', arg.string().env('DEPLOY_TARGET'))
|
|
1153
1372
|
* .flag('force', flag.boolean().alias('f'))
|
|
1154
1373
|
* .flag('region', flag.enum(['us', 'eu', 'ap']).env('REGION'))
|
|
1155
1374
|
* .middleware(auth)
|
|
1156
|
-
* .action(async ({ args, flags, ctx, out }) => {
|
|
1375
|
+
* .action(async ({ args, flags, ctx, out, meta }) => {
|
|
1157
1376
|
* args.target; // string
|
|
1158
1377
|
* flags.force; // boolean
|
|
1159
1378
|
* flags.region; // 'us' | 'eu' | 'ap' | undefined
|
|
1160
1379
|
* ctx.user; // User (from auth middleware)
|
|
1380
|
+
* meta.command; // string
|
|
1161
1381
|
*
|
|
1162
1382
|
* const spinner = out.spinner('Deploying...');
|
|
1163
1383
|
* await deploy(args.target, { force: flags.force });
|
|
1164
1384
|
* spinner.stop();
|
|
1165
1385
|
* out.log('Done');
|
|
1166
1386
|
* });
|
|
1387
|
+
* ```
|
|
1167
1388
|
*
|
|
1168
1389
|
* @returns The builder (for chaining).
|
|
1169
1390
|
*/
|
|
1170
1391
|
action(handler: ActionHandler<F, A, C>): CommandBuilder<F, A, C> {
|
|
1171
1392
|
return new CommandBuilder(
|
|
1172
1393
|
{ ...this.schema, hasAction: true },
|
|
1173
|
-
handler,
|
|
1394
|
+
handler as unknown as ErasedActionHandler,
|
|
1174
1395
|
this._subcommands,
|
|
1175
1396
|
this._executionSteps,
|
|
1176
1397
|
);
|
|
@@ -1186,6 +1407,8 @@ class CommandBuilder<
|
|
|
1186
1407
|
*
|
|
1187
1408
|
* @example
|
|
1188
1409
|
* ```ts
|
|
1410
|
+
* import { arg, command, flag } from '@kjanat/dreamcli';
|
|
1411
|
+
*
|
|
1189
1412
|
* const greet = command('greet')
|
|
1190
1413
|
* .arg('name', arg.string())
|
|
1191
1414
|
* .flag('loud', flag.boolean())
|
|
@@ -1216,7 +1439,7 @@ function command(name: string): CommandBuilder {
|
|
|
1216
1439
|
/**
|
|
1217
1440
|
* Create a command builder intended for use as a command group.
|
|
1218
1441
|
*
|
|
1219
|
-
* Semantically identical to
|
|
1442
|
+
* Semantically identical to {@linkcode command | command()} — a group is simply a command that
|
|
1220
1443
|
* has subcommands registered via `.command()`. The separate factory
|
|
1221
1444
|
* communicates intent: groups organise subcommands, leaf commands have actions.
|
|
1222
1445
|
*
|
|
@@ -1252,6 +1475,7 @@ export type {
|
|
|
1252
1475
|
CommandSchema,
|
|
1253
1476
|
DeriveHandler,
|
|
1254
1477
|
DeriveParams,
|
|
1478
|
+
ErasedActionHandler,
|
|
1255
1479
|
ErasedCommand,
|
|
1256
1480
|
ErasedDeriveHandler,
|
|
1257
1481
|
ErasedInteractiveResolver,
|
|
@@ -1259,5 +1483,8 @@ export type {
|
|
|
1259
1483
|
InteractiveResolver,
|
|
1260
1484
|
InteractiveResult,
|
|
1261
1485
|
Out,
|
|
1486
|
+
RunnableCommand,
|
|
1487
|
+
WidenContext,
|
|
1488
|
+
WidenDerivedContext,
|
|
1262
1489
|
};
|
|
1263
1490
|
export { CommandBuilder, command, group };
|