@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,12 +1,15 @@
|
|
|
1
1
|
import { ActivityEvent, Fallback, ProgressHandle, ProgressOptions, SpinnerHandle, SpinnerOptions, TableColumn, TableFormat, TableOptions, TableStream } from "./activity.mjs";
|
|
2
2
|
import { NumberConstraintViolation, NumberConstraints, describeNumberConstraintViolation, validateNumberConstraints } from "./number-constraints.mjs";
|
|
3
|
-
import { InferStandardInput, InferStandardOutput, StandardSchemaV1, StandardSchemaV1FailureResult, StandardSchemaV1Issue, StandardSchemaV1Options, StandardSchemaV1PathSegment, StandardSchemaV1Props, StandardSchemaV1Result, StandardSchemaV1SuccessResult, StandardSchemaV1Types } from "./standard.mjs";
|
|
4
|
-
import { ARG_KINDS, ARG_PRESENCES, ArgBuilder, ArgConfig, ArgFactory, ArgKind, ArgParseFn, ArgPresence, ArgSchema, InferArg, InferArgs, ResolvedArgValue, WithArgPresence, WithVariadic, arg, createArgSchema } from "./arg.mjs";
|
|
5
3
|
import { ConfirmPromptConfig, InputPromptConfig, MultiselectPromptConfig, PROMPT_KINDS, PromptConfig, PromptConfigBase, PromptKind, PromptResult, SelectChoice, SelectPromptConfig } from "./prompt.mjs";
|
|
6
|
-
import {
|
|
7
|
-
import {
|
|
8
|
-
import {
|
|
9
|
-
import {
|
|
4
|
+
import { InferStandardInput, InferStandardOutput, StandardSchemaV1, StandardSchemaV1FailureResult, StandardSchemaV1Issue, StandardSchemaV1Options, StandardSchemaV1PathSegment, StandardSchemaV1Props, StandardSchemaV1Result, StandardSchemaV1SuccessResult, StandardSchemaV1Types } from "./standard.mjs";
|
|
5
|
+
import { STDIN_CONSUMES, STDIN_WHENS, StdinBinding, StdinConsume, StdinOptions, StdinWhen } from "./stdin.mjs";
|
|
6
|
+
import { StringConstraintViolation, StringConstraints, describeStringConstraintViolation, stringConstraintDetails, validateStringConstraints } from "./string-constraints.mjs";
|
|
7
|
+
import { DateFlagOptions, PathChecks, PathFlagOptions, UrlFlagOptions } from "./value-parsers.mjs";
|
|
8
|
+
import { ArrayFlagDefinition, BooleanFlagDefinition, CountFlagDefinition, CustomFlagDefinition, DuplicatePolicy, EnumFlagDefinition, FLAG_KINDS, FLAG_PRESENCES, FlagAlias, FlagBuilder, FlagConfig, FlagDefinition, FlagDefinitionBase, FlagDefinitionByKind, FlagDefinitionOverrides, FlagFactory, FlagKind, FlagNegation, FlagParseFn, FlagPresence, FlagSchema, InferFlag, InferFlags, KeyValueFlagDefinition, NumberFlagDefinition, ResolvedValue, StringElementConfig, StringFlagDefinition, WithPresence, WithoutElementEligibility, createFlagSchema, flag, getFlagNegatedName } from "./flag.mjs";
|
|
9
|
+
import { DUPLICATE_KEYS, DuplicateKeys, SPLIT_FORMATS, SourceSplitBinding, SplitBinding, SplitFormat, SplitOptions, SplitPolicy, SplitSetting } from "./cardinality.mjs";
|
|
10
|
+
import { ARG_KINDS, ARG_PRESENCES, AllowedArgPromptConfig, ArgBuilder, ArgConfig, ArgDefaultValue, ArgDefinition, ArgDefinitionBase, ArgDefinitionByKind, ArgDefinitionOverrides, ArgFactory, ArgKind, ArgParseFn, ArgPresence, ArgSchema, BooleanArgDefinition, CustomArgDefinition, EnumArgDefinition, InferArg, InferArgs, KeyValueArgDefinition, NumberArgDefinition, PromptConfigByArgKind, ResolvedArgValue, StringArgDefinition, StringArgElementConfig, WithArgPresence, WithVariadic, WithoutArgElementEligibility, arg, createArgSchema } from "./arg.mjs";
|
|
11
|
+
import { Middleware, MiddlewareHandler, MiddlewareParams, middleware } from "./middleware.mjs";
|
|
12
|
+
import { InputSources, ResolutionProvenance, SourcesOf, wasExplicit } from "./provenance.mjs";
|
|
13
|
+
import { ActionHandler, ActionParams, AnyCommandBuilder, CommandArgEntry, CommandArgEntryDefinition, CommandBuilder, CommandDefinition, CommandExample, CommandMeta, CommandSchema, DeriveHandler, DeriveParams, ExampleCommand, ExampleMeta, InteractiveParams, InteractiveResolver, InteractiveResult, Out, command, createCommandSchema, group, resolveExampleCommand } from "./command.mjs";
|
|
10
14
|
import { RunOptions, RunResult } from "./run.mjs";
|
|
11
|
-
|
|
12
|
-
export { ARG_KINDS, ARG_PRESENCES, type ActionHandler, type ActionParams, type ActivityEvent, type AnyCommandBuilder, ArgBuilder, type ArgConfig, type ArgFactory, type ArgKind, type ArgParseFn, type ArgPresence, type ArgSchema, type CommandArgEntry, CommandBuilder, type CommandConfig, type CommandExample, type CommandMeta, type CommandSchema, type ConfirmPromptConfig, type DateFlagOptions, type DeriveHandler, type DeriveParams, type DuplicatePolicy, type ErasedCommand, type ErasedDeriveHandler, type ErasedInteractiveResolver, type ErasedMiddlewareHandler, type ExampleCommand, type ExampleMeta, FLAG_KINDS, FLAG_PRESENCES, type Fallback, type FlagAlias, FlagBuilder, type FlagConfig, type FlagFactory, type FlagKind, type FlagNegation, type FlagParseFn, type FlagPresence, type FlagSchema, type FlagSchemaOverrides, type InferArg, type InferArgs, type InferFlag, type InferFlags, type InferStandardInput, type InferStandardOutput, type InputPromptConfig, type InteractiveParams, type InteractiveResolver, type InteractiveResult, type Middleware, type MiddlewareHandler, type MiddlewareParams, type MultiselectPromptConfig, type NumberConstraintViolation, type NumberConstraints, type Out, PROMPT_KINDS, type PathChecks, type PathFlagOptions, type ProgressHandle, type ProgressOptions, type PromptConfig, type PromptConfigBase, type PromptKind, type PromptResult, type ResolvedArgValue, type ResolvedValue, type RunOptions, type RunResult, type SelectChoice, type SelectPromptConfig, type SpinnerHandle, type SpinnerOptions, type StandardSchemaV1, type StandardSchemaV1FailureResult, type StandardSchemaV1Issue, type StandardSchemaV1Options, type StandardSchemaV1PathSegment, type StandardSchemaV1Props, type StandardSchemaV1Result, type StandardSchemaV1SuccessResult, type StandardSchemaV1Types, type StringConstraintViolation, type StringConstraints, type TableColumn, type TableFormat, type TableOptions, type TableStream, type UrlFlagOptions, type WithArgPresence, type WithPresence, type WithVariadic, arg, command, createArgSchema, createSchema, describeNumberConstraintViolation, describeStringConstraintViolation, flag, getFlagNegatedName, group, middleware, resolveExampleCommand, validateNumberConstraints, validateStringConstraints };
|
|
15
|
+
export { ARG_KINDS, ARG_PRESENCES, type ActionHandler, type ActionParams, type ActivityEvent, type AllowedArgPromptConfig, type AnyCommandBuilder, ArgBuilder, type ArgConfig, type ArgDefaultValue, type ArgDefinition, type ArgDefinitionBase, type ArgDefinitionByKind, type ArgDefinitionOverrides, type ArgFactory, type ArgKind, type ArgParseFn, type ArgPresence, type ArgSchema, type ArrayFlagDefinition, type BooleanArgDefinition, type BooleanFlagDefinition, type CommandArgEntry, type CommandArgEntryDefinition, CommandBuilder, type CommandDefinition, type CommandExample, type CommandMeta, type CommandSchema, type ConfirmPromptConfig, type CountFlagDefinition, type CustomArgDefinition, type CustomFlagDefinition, DUPLICATE_KEYS, type DateFlagOptions, type DeriveHandler, type DeriveParams, type DuplicateKeys, type DuplicatePolicy, type EnumArgDefinition, type EnumFlagDefinition, type ExampleCommand, type ExampleMeta, FLAG_KINDS, FLAG_PRESENCES, type Fallback, type FlagAlias, FlagBuilder, type FlagConfig, type FlagDefinition, type FlagDefinitionBase, type FlagDefinitionByKind, type FlagDefinitionOverrides, type FlagFactory, type FlagKind, type FlagNegation, type FlagParseFn, type FlagPresence, type FlagSchema, type InferArg, type InferArgs, type InferFlag, type InferFlags, type InferStandardInput, type InferStandardOutput, type InputPromptConfig, type InputSources, type InteractiveParams, type InteractiveResolver, type InteractiveResult, type KeyValueArgDefinition, type KeyValueFlagDefinition, type Middleware, type MiddlewareHandler, type MiddlewareParams, type MultiselectPromptConfig, type NumberArgDefinition, type NumberConstraintViolation, type NumberConstraints, type NumberFlagDefinition, type Out, PROMPT_KINDS, type PathChecks, type PathFlagOptions, type ProgressHandle, type ProgressOptions, type PromptConfig, type PromptConfigBase, type PromptConfigByArgKind, type PromptKind, type PromptResult, type ResolutionProvenance, type ResolvedArgValue, type ResolvedValue, type RunOptions, type RunResult, SPLIT_FORMATS, STDIN_CONSUMES, STDIN_WHENS, type SelectChoice, type SelectPromptConfig, type SourceSplitBinding, type SourcesOf, type SpinnerHandle, type SpinnerOptions, type SplitBinding, type SplitFormat, type SplitOptions, type SplitPolicy, type SplitSetting, type StandardSchemaV1, type StandardSchemaV1FailureResult, type StandardSchemaV1Issue, type StandardSchemaV1Options, type StandardSchemaV1PathSegment, type StandardSchemaV1Props, type StandardSchemaV1Result, type StandardSchemaV1SuccessResult, type StandardSchemaV1Types, type StdinBinding, type StdinConsume, type StdinOptions, type StdinWhen, type StringArgDefinition, type StringArgElementConfig, type StringConstraintViolation, type StringConstraints, type StringElementConfig, type StringFlagDefinition, type TableColumn, type TableFormat, type TableOptions, type TableStream, type UrlFlagOptions, type WithArgPresence, type WithPresence, type WithVariadic, type WithoutArgElementEligibility, type WithoutElementEligibility, arg, command, createArgSchema, createCommandSchema, createFlagSchema, describeNumberConstraintViolation, describeStringConstraintViolation, flag, getFlagNegatedName, group, middleware, resolveExampleCommand, stringConstraintDetails, validateNumberConstraints, validateStringConstraints, wasExplicit };
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import { describeNumberConstraintViolation } from "./number-constraints.mjs";
|
|
2
|
+
import { describeStringConstraintViolation, stringConstraintDetails } from "./string-constraints.mjs";
|
|
3
|
+
import { DUPLICATE_KEYS, SPLIT_FORMATS } from "./cardinality.mjs";
|
|
4
|
+
import "./stdin.mjs";
|
|
5
|
+
import { FlagBuilder, createFlagSchema, flag, getFlagNegatedName } from "./flag.mjs";
|
|
6
|
+
import { ArgBuilder, arg, createArgSchema } from "./arg.mjs";
|
|
7
|
+
import { CommandBuilder, command, createCommandSchema, group, resolveExampleCommand } from "./command.mjs";
|
|
8
|
+
import { middleware } from "./middleware.mjs";
|
|
9
|
+
import { wasExplicit } from "./provenance.mjs";
|
|
10
|
+
export { ArgBuilder, CommandBuilder, DUPLICATE_KEYS, FlagBuilder, SPLIT_FORMATS, arg, command, createArgSchema, createCommandSchema, createFlagSchema, describeNumberConstraintViolation, describeStringConstraintViolation, flag, getFlagNegatedName, group, middleware, resolveExampleCommand, stringConstraintDetails, wasExplicit };
|
|
@@ -1,17 +1,25 @@
|
|
|
1
|
-
import { CommandMeta, Out } from "./command.mjs";
|
|
1
|
+
import { CommandMeta, ErasedInputSources, Out } from "./command.mjs";
|
|
2
2
|
//#region src/core/schema/middleware.d.ts
|
|
3
3
|
/**
|
|
4
4
|
* Parameters received by a middleware function at runtime.
|
|
5
5
|
*
|
|
6
|
-
* Middleware receives erased args
|
|
7
|
-
* of commands) plus the accumulated context from prior middleware
|
|
8
|
-
* `next` function to continue the chain.
|
|
6
|
+
* Middleware receives erased args, flags, and provenance (since it's defined
|
|
7
|
+
* independently of commands) plus the accumulated context from prior middleware
|
|
8
|
+
* and a `next` function to continue the chain.
|
|
9
9
|
*/
|
|
10
10
|
interface MiddlewareParams {
|
|
11
11
|
/** Fully resolved positional arguments (type-erased). */
|
|
12
12
|
readonly args: Readonly<Record<string, unknown>>;
|
|
13
13
|
/** Fully resolved flags (type-erased). */
|
|
14
14
|
readonly flags: Readonly<Record<string, unknown>>;
|
|
15
|
+
/**
|
|
16
|
+
* Where each resolved value came from, keyed like `flags` and `args`.
|
|
17
|
+
*
|
|
18
|
+
* Erased alongside them, so any key reads as `ResolutionProvenance |
|
|
19
|
+
* undefined`. A key the bound command never declared, and one an input
|
|
20
|
+
* resolved no value for, both read `undefined`.
|
|
21
|
+
*/
|
|
22
|
+
readonly sources: ErasedInputSources;
|
|
15
23
|
/** Context accumulated from previous middleware in the chain. */
|
|
16
24
|
readonly ctx: Readonly<Record<string, unknown>>;
|
|
17
25
|
/** Output channel. */
|
|
@@ -28,12 +36,10 @@ interface MiddlewareParams {
|
|
|
28
36
|
readonly next: (additions: Record<string, unknown>) => Promise<void>;
|
|
29
37
|
}
|
|
30
38
|
/**
|
|
31
|
-
* Type-erased middleware handler stored on
|
|
39
|
+
* Type-erased middleware handler stored on the command builder.
|
|
32
40
|
*
|
|
33
41
|
* At runtime, all middleware handlers have this signature. The phantom
|
|
34
42
|
* `Output` type on {@linkcode Middleware} is erased.
|
|
35
|
-
*
|
|
36
|
-
* @internal
|
|
37
43
|
*/
|
|
38
44
|
type ErasedMiddlewareHandler = (params: MiddlewareParams) => void | Promise<void>;
|
|
39
45
|
/**
|
|
@@ -45,6 +51,7 @@ type ErasedMiddlewareHandler = (params: MiddlewareParams) => void | Promise<void
|
|
|
45
51
|
type MiddlewareHandler<Output extends Record<string, unknown>> = (params: {
|
|
46
52
|
readonly args: Readonly<Record<string, unknown>>;
|
|
47
53
|
readonly flags: Readonly<Record<string, unknown>>;
|
|
54
|
+
readonly sources: ErasedInputSources;
|
|
48
55
|
readonly ctx: Readonly<Record<string, unknown>>;
|
|
49
56
|
readonly out: Out;
|
|
50
57
|
readonly meta: CommandMeta;
|
|
@@ -53,7 +60,6 @@ type MiddlewareHandler<Output extends Record<string, unknown>> = (params: {
|
|
|
53
60
|
}) => void | Promise<void>;
|
|
54
61
|
/**
|
|
55
62
|
* Internal runtime representation of middleware.
|
|
56
|
-
* @internal
|
|
57
63
|
*/
|
|
58
64
|
interface MiddlewareImpl {
|
|
59
65
|
readonly _handler: ErasedMiddlewareHandler;
|
|
@@ -79,10 +85,7 @@ interface MiddlewareImpl {
|
|
|
79
85
|
* });
|
|
80
86
|
* ```
|
|
81
87
|
*/
|
|
82
|
-
type Middleware<Output extends Record<string, unknown>> = MiddlewareImpl & {
|
|
83
|
-
/** @internal Phantom type brand — compile-time only. */
|
|
84
|
-
readonly _output: Output;
|
|
85
|
-
};
|
|
88
|
+
type Middleware<Output extends Record<string, unknown>> = MiddlewareImpl & {};
|
|
86
89
|
/**
|
|
87
90
|
* Create a middleware definition.
|
|
88
91
|
*
|
|
@@ -45,18 +45,18 @@ interface NumberConstraints {
|
|
|
45
45
|
* `min` / `max` carry the offending bound so callers can render it.
|
|
46
46
|
*/
|
|
47
47
|
type NumberConstraintViolation = {
|
|
48
|
-
readonly kind:
|
|
48
|
+
readonly kind: "finite";
|
|
49
49
|
} | {
|
|
50
|
-
readonly kind:
|
|
50
|
+
readonly kind: "int";
|
|
51
51
|
} | {
|
|
52
|
-
readonly kind:
|
|
52
|
+
readonly kind: "min";
|
|
53
53
|
readonly bound: number;
|
|
54
54
|
} | {
|
|
55
|
-
readonly kind:
|
|
55
|
+
readonly kind: "max";
|
|
56
56
|
readonly bound: number;
|
|
57
57
|
};
|
|
58
58
|
/** Default for {@link NumberConstraints.finite} — reject `Infinity` unless opted out. */
|
|
59
|
-
declare const DEFAULT_FINITE
|
|
59
|
+
declare const DEFAULT_FINITE: boolean;
|
|
60
60
|
/**
|
|
61
61
|
* Validate a numeric value against constraints.
|
|
62
62
|
*
|
|
@@ -28,7 +28,7 @@ interface PromptConfigBase {
|
|
|
28
28
|
/** Yes/no confirmation prompt — maps to `boolean` flags. Part of {@link PromptConfig}. */
|
|
29
29
|
interface ConfirmPromptConfig extends PromptConfigBase {
|
|
30
30
|
/** Discriminator identifying this as a yes/no confirmation prompt. */
|
|
31
|
-
readonly kind:
|
|
31
|
+
readonly kind: "confirm";
|
|
32
32
|
/**
|
|
33
33
|
* Value used when the user submits an empty line (presses Enter). Also
|
|
34
34
|
* drives the displayed hint: `true` → `(Y/n)`, `false` → `(y/N)`.
|
|
@@ -39,7 +39,7 @@ interface ConfirmPromptConfig extends PromptConfigBase {
|
|
|
39
39
|
/** Free-text input prompt — maps to `string` and `number` flags. Part of {@link PromptConfig}. */
|
|
40
40
|
interface InputPromptConfig extends PromptConfigBase {
|
|
41
41
|
/** Discriminator identifying this as a free-text input prompt. */
|
|
42
|
-
readonly kind:
|
|
42
|
+
readonly kind: "input";
|
|
43
43
|
/** Placeholder text shown before user types (informational only). */
|
|
44
44
|
readonly placeholder?: string;
|
|
45
45
|
/**
|
|
@@ -60,7 +60,7 @@ interface InputPromptConfig extends PromptConfigBase {
|
|
|
60
60
|
/** Single-selection prompt — maps to `enum` flags or any flag with {@link SelectChoice choices}. Part of {@link PromptConfig}. */
|
|
61
61
|
interface SelectPromptConfig extends PromptConfigBase {
|
|
62
62
|
/** Discriminator identifying this as a single-selection prompt. */
|
|
63
|
-
readonly kind:
|
|
63
|
+
readonly kind: "select";
|
|
64
64
|
/**
|
|
65
65
|
* Available choices. When omitted for `enum` flags, the enum values
|
|
66
66
|
* from the flag schema are used automatically.
|
|
@@ -73,7 +73,7 @@ interface SelectPromptConfig extends PromptConfigBase {
|
|
|
73
73
|
*/
|
|
74
74
|
interface MultiselectPromptConfig extends PromptConfigBase {
|
|
75
75
|
/** Discriminator identifying this as a multi-selection prompt. */
|
|
76
|
-
readonly kind:
|
|
76
|
+
readonly kind: "multiselect";
|
|
77
77
|
/**
|
|
78
78
|
* Available choices. When omitted for `array` flags with enum elements,
|
|
79
79
|
* the enum values from the element schema are used automatically.
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
//#region src/core/schema/provenance.d.ts
|
|
2
|
+
/**
|
|
3
|
+
* Where a resolved value came from.
|
|
4
|
+
*
|
|
5
|
+
* Resolution records one {@link ResolutionProvenance} per input that produced a
|
|
6
|
+
* value, and the same record reaches a handler through `sources` and a
|
|
7
|
+
* `resolve()` caller through `ResolveResult.provenance`. {@link wasExplicit}
|
|
8
|
+
* derives the explicit-versus-defaulted question from it.
|
|
9
|
+
*
|
|
10
|
+
* @module dreamcli/core/schema/provenance
|
|
11
|
+
*/
|
|
12
|
+
/**
|
|
13
|
+
* Which stage produced a resolved value, and how.
|
|
14
|
+
*
|
|
15
|
+
* `via` and `trigger` distinguish the two ways stdin delivers bytes. An explicit
|
|
16
|
+
* `-` keeps CLI precedence and reports `{ stage: 'cli', via: 'stdin', trigger:
|
|
17
|
+
* 'dash' }`; an absent input takes the fallback stage between CLI and env and
|
|
18
|
+
* reports `{ stage: 'stdin', via: 'stdin', trigger: 'fallback' }`.
|
|
19
|
+
*
|
|
20
|
+
* @example
|
|
21
|
+
* ```ts
|
|
22
|
+
* command('deploy')
|
|
23
|
+
* .flag('region', flag.string().env('REGION').default('us'))
|
|
24
|
+
* .action(({ sources }) => {
|
|
25
|
+
* const region = sources.flags.region;
|
|
26
|
+
* if (region?.stage === 'env') console.log(`from ${region.envVar}`);
|
|
27
|
+
* });
|
|
28
|
+
* ```
|
|
29
|
+
*/
|
|
30
|
+
type ResolutionProvenance = {
|
|
31
|
+
readonly stage: "cli";
|
|
32
|
+
} | {
|
|
33
|
+
readonly stage: "cli";
|
|
34
|
+
readonly via: "stdin";
|
|
35
|
+
readonly trigger: "dash";
|
|
36
|
+
} | {
|
|
37
|
+
readonly stage: "stdin";
|
|
38
|
+
readonly via: "stdin";
|
|
39
|
+
readonly trigger: "fallback";
|
|
40
|
+
} | {
|
|
41
|
+
readonly stage: "env";
|
|
42
|
+
readonly envVar: string;
|
|
43
|
+
} | {
|
|
44
|
+
readonly stage: "config";
|
|
45
|
+
readonly configPath: string;
|
|
46
|
+
} | {
|
|
47
|
+
readonly stage: "prompt";
|
|
48
|
+
} | {
|
|
49
|
+
readonly stage: "default";
|
|
50
|
+
};
|
|
51
|
+
/**
|
|
52
|
+
* Provenance of every input of one surface, keyed by input name.
|
|
53
|
+
*
|
|
54
|
+
* An input that resolved no value has no record, so every member is optional in
|
|
55
|
+
* value even though the key set is the surface's own.
|
|
56
|
+
*
|
|
57
|
+
* @typeParam T - The record of flag or arg builders whose keys this mirrors.
|
|
58
|
+
*/
|
|
59
|
+
type SourcesOf<T> = { readonly [K in keyof T]: ResolutionProvenance | undefined; };
|
|
60
|
+
/**
|
|
61
|
+
* Where each of a command's resolved values came from.
|
|
62
|
+
*
|
|
63
|
+
* Handed to an action, derive, or middleware handler as `sources`, keyed by the
|
|
64
|
+
* same names as `flags` and `args`.
|
|
65
|
+
*
|
|
66
|
+
* @typeParam F - The command's flag builders.
|
|
67
|
+
* @typeParam A - The command's arg builders.
|
|
68
|
+
*/
|
|
69
|
+
interface InputSources<F, A> {
|
|
70
|
+
/** Provenance of every declared flag, keyed by flag name. */
|
|
71
|
+
readonly flags: SourcesOf<F>;
|
|
72
|
+
/** Provenance of every declared arg, keyed by arg name. */
|
|
73
|
+
readonly args: SourcesOf<A>;
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* Whether a value came from somewhere other than its declared default.
|
|
77
|
+
*
|
|
78
|
+
* Every stage but `'default'` means the value was supplied: typed on the command
|
|
79
|
+
* line, piped, exported, written in a config file, or answered at a prompt. An
|
|
80
|
+
* input that resolved no value at all has no record and is not explicit.
|
|
81
|
+
*
|
|
82
|
+
* Read `stage` directly for a narrower question, such as `stage === 'cli'` for
|
|
83
|
+
* "the user typed it on this command line".
|
|
84
|
+
*
|
|
85
|
+
* @param source - The provenance record of one input, or `undefined`.
|
|
86
|
+
* @returns `true` when a source other than the default produced the value.
|
|
87
|
+
*
|
|
88
|
+
* @example
|
|
89
|
+
* ```ts
|
|
90
|
+
* command('build')
|
|
91
|
+
* .flag('out', flag.string().default('dist'))
|
|
92
|
+
* .action(({ sources, out }) => {
|
|
93
|
+
* if (wasExplicit(sources.flags.out)) out.info('using an overridden output');
|
|
94
|
+
* });
|
|
95
|
+
* ```
|
|
96
|
+
*/
|
|
97
|
+
declare function wasExplicit(source: ResolutionProvenance | undefined): boolean;
|
|
98
|
+
//#endregion
|
|
99
|
+
export { type InputSources, type ResolutionProvenance, type SourcesOf, wasExplicit };
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
//#region src/core/schema/provenance.ts
|
|
2
|
+
/**
|
|
3
|
+
* Whether a value came from somewhere other than its declared default.
|
|
4
|
+
*
|
|
5
|
+
* Every stage but `'default'` means the value was supplied: typed on the command
|
|
6
|
+
* line, piped, exported, written in a config file, or answered at a prompt. An
|
|
7
|
+
* input that resolved no value at all has no record and is not explicit.
|
|
8
|
+
*
|
|
9
|
+
* Read `stage` directly for a narrower question, such as `stage === 'cli'` for
|
|
10
|
+
* "the user typed it on this command line".
|
|
11
|
+
*
|
|
12
|
+
* @param source - The provenance record of one input, or `undefined`.
|
|
13
|
+
* @returns `true` when a source other than the default produced the value.
|
|
14
|
+
*
|
|
15
|
+
* @example
|
|
16
|
+
* ```ts
|
|
17
|
+
* command('build')
|
|
18
|
+
* .flag('out', flag.string().default('dist'))
|
|
19
|
+
* .action(({ sources, out }) => {
|
|
20
|
+
* if (wasExplicit(sources.flags.out)) out.info('using an overridden output');
|
|
21
|
+
* });
|
|
22
|
+
* ```
|
|
23
|
+
*/
|
|
24
|
+
function wasExplicit(source) {
|
|
25
|
+
return source !== void 0 && source.stage !== "default";
|
|
26
|
+
}
|
|
27
|
+
//#endregion
|
|
28
|
+
export { wasExplicit };
|
|
@@ -1,11 +1,9 @@
|
|
|
1
|
-
import { ActivityEvent } from "./activity.mjs";
|
|
2
1
|
import { Verbosity } from "../output/contracts.mjs";
|
|
3
|
-
import {
|
|
4
|
-
import { PromptEngine, TestAnswer } from "../prompt/index.mjs";
|
|
5
|
-
import { CLIPlugin } from "../cli/plugin.mjs";
|
|
2
|
+
import { ActivityEvent } from "./activity.mjs";
|
|
6
3
|
import { CLIError } from "../errors/index.mjs";
|
|
7
4
|
import { HelpOptions } from "../help/index.mjs";
|
|
8
|
-
import
|
|
5
|
+
import "../output/index.mjs";
|
|
6
|
+
import { PromptEngine, TestAnswer } from "../prompt/index.mjs";
|
|
9
7
|
import { ParseOptions } from "../parse/index.mjs";
|
|
10
8
|
//#region src/core/schema/run.d.ts
|
|
11
9
|
/**
|
|
@@ -17,31 +15,33 @@ import { ParseOptions } from "../parse/index.mjs";
|
|
|
17
15
|
*/
|
|
18
16
|
interface RunOptions {
|
|
19
17
|
/**
|
|
20
|
-
* Environment variables for flag resolution.
|
|
18
|
+
* Environment variables for flag and arg resolution.
|
|
21
19
|
*
|
|
22
|
-
*
|
|
23
|
-
*
|
|
20
|
+
* Inputs with `.env('VAR')` configured resolve from this record when CLI
|
|
21
|
+
* and stdin produce nothing
|
|
22
|
+
* (CLI → stdin → env → config → prompt → default).
|
|
24
23
|
*/
|
|
25
24
|
readonly env?: Readonly<Record<string, string | undefined>>;
|
|
26
25
|
/**
|
|
27
|
-
* Configuration object for flag resolution.
|
|
26
|
+
* Configuration object for flag and arg resolution.
|
|
28
27
|
*
|
|
29
|
-
*
|
|
30
|
-
*
|
|
31
|
-
*
|
|
28
|
+
* Inputs with `.config('path')` configured resolve from this record when
|
|
29
|
+
* CLI, stdin, and env produce nothing
|
|
30
|
+
* (CLI → stdin → env → config → prompt → default).
|
|
31
|
+
* Config is plain JSON, so file loading is the caller's responsibility.
|
|
32
32
|
*/
|
|
33
33
|
readonly config?: Readonly<Record<string, unknown>>;
|
|
34
34
|
/**
|
|
35
|
-
* Full stdin contents for args configured with `.stdin()`.
|
|
35
|
+
* Full stdin contents for flags and args configured with `.stdin()`.
|
|
36
36
|
*
|
|
37
37
|
* Lets tests inject piped input without a runtime adapter.
|
|
38
38
|
*/
|
|
39
39
|
readonly stdinData?: string | null;
|
|
40
40
|
/**
|
|
41
|
-
* Prompt engine for interactive flag resolution.
|
|
41
|
+
* Prompt engine for interactive flag and arg resolution.
|
|
42
42
|
*
|
|
43
|
-
* When provided,
|
|
44
|
-
* after CLI
|
|
43
|
+
* When provided, inputs with `.prompt()` configured that have no value
|
|
44
|
+
* after CLI, stdin, env, and config resolution are prompted interactively.
|
|
45
45
|
*
|
|
46
46
|
* When absent (and `answers` is also absent), prompting is skipped
|
|
47
47
|
* and resolution falls through to default/required.
|
|
@@ -60,16 +60,17 @@ interface RunOptions {
|
|
|
60
60
|
*/
|
|
61
61
|
readonly answers?: readonly TestAnswer[];
|
|
62
62
|
/**
|
|
63
|
-
* Filesystem probe for `flag.path()` checks: reports what
|
|
64
|
-
* path (`'file'`, `'directory'`, or `null` for nothing).
|
|
63
|
+
* Filesystem probe for `flag.path()` and `arg.path()` checks: reports what
|
|
64
|
+
* exists at a path (`'file'`, `'directory'`, or `null` for nothing).
|
|
65
65
|
*
|
|
66
66
|
* `CLIBuilder.run()` supplies the runtime adapter's probe automatically.
|
|
67
67
|
* When absent (process-free `.execute()` / `runCommand()` without an
|
|
68
68
|
* override), path checks are skipped.
|
|
69
69
|
*/
|
|
70
|
-
readonly stat?: (path: string) => Promise<
|
|
70
|
+
readonly stat?: (path: string) => Promise<"file" | "directory" | null>;
|
|
71
71
|
/**
|
|
72
|
-
* Recursive directory creation for `flag.path()` `create`
|
|
72
|
+
* Recursive directory creation for `flag.path()` and `arg.path()` `create`
|
|
73
|
+
* checks.
|
|
73
74
|
*
|
|
74
75
|
* `CLIBuilder.run()` supplies the runtime adapter's implementation
|
|
75
76
|
* automatically. When absent, missing paths are not created.
|
|
@@ -100,20 +101,6 @@ interface RunOptions {
|
|
|
100
101
|
* @defaultValue `false`
|
|
101
102
|
*/
|
|
102
103
|
readonly isTTY?: boolean;
|
|
103
|
-
/**
|
|
104
|
-
* Output channel override used by live CLI execution.
|
|
105
|
-
*
|
|
106
|
-
* @internal — `CLIBuilder.run()` passes a real output channel so activity renders to
|
|
107
|
-
* the terminal instead of being captured.
|
|
108
|
-
*/
|
|
109
|
-
readonly out?: Out;
|
|
110
|
-
/**
|
|
111
|
-
* Capture buffers override paired with `out`.
|
|
112
|
-
*
|
|
113
|
-
* @internal — when omitted, `runCommand()` creates empty buffers for the
|
|
114
|
-
* returned {@linkcode RunResult} while writing directly to the provided `out`.
|
|
115
|
-
*/
|
|
116
|
-
readonly captured?: CapturedOutput;
|
|
117
104
|
/**
|
|
118
105
|
* Help formatting options (width, binName).
|
|
119
106
|
* Used when `--help` is detected.
|
|
@@ -129,32 +116,6 @@ interface RunOptions {
|
|
|
129
116
|
* @defaultValue `{ caseParity: true }`
|
|
130
117
|
*/
|
|
131
118
|
readonly flags?: ParseOptions;
|
|
132
|
-
/**
|
|
133
|
-
* Command schema with propagated flags merged in.
|
|
134
|
-
*
|
|
135
|
-
* When provided, used for parsing and resolution instead of `cmd.schema`.
|
|
136
|
-
* Set by the CLI dispatch layer after collecting propagated flags from
|
|
137
|
-
* the command ancestry path.
|
|
138
|
-
*
|
|
139
|
-
* @internal — set by dispatch layer, not for public use.
|
|
140
|
-
*/
|
|
141
|
-
readonly mergedSchema?: CommandSchema;
|
|
142
|
-
/**
|
|
143
|
-
* CLI program metadata passed to action handlers and middleware.
|
|
144
|
-
*
|
|
145
|
-
* When provided (by CLI dispatch layer), handlers receive this as `meta`.
|
|
146
|
-
* When absent (standalone `runCommand()`), a minimal meta is constructed
|
|
147
|
-
* from the command's own schema.
|
|
148
|
-
*
|
|
149
|
-
* @internal — populated by CLI dispatch, not for public use.
|
|
150
|
-
*/
|
|
151
|
-
readonly meta?: CommandMeta;
|
|
152
|
-
/**
|
|
153
|
-
* CLI plugins registered on the parent `CLIBuilder`.
|
|
154
|
-
*
|
|
155
|
-
* @internal — threaded through from CLI dispatch.
|
|
156
|
-
*/
|
|
157
|
-
readonly plugins?: readonly CLIPlugin[];
|
|
158
119
|
}
|
|
159
120
|
/**
|
|
160
121
|
* Structured result from {@linkcode runCommand}.
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
import { PromptConfig } from "./prompt.mjs";
|
|
2
|
+
import { StdinBinding, StdinConsume, StdinWhen } from "./stdin.mjs";
|
|
3
|
+
import { FlagSchema } from "./flag.mjs";
|
|
4
|
+
import { SplitPolicy } from "./cardinality.mjs";
|
|
5
|
+
//#region src/core/schema/source.d.ts
|
|
6
|
+
/**
|
|
7
|
+
* Ordered resolution stages, highest precedence first.
|
|
8
|
+
*
|
|
9
|
+
* Both surfaces walk this one list. An explicit `-` is CLI-sourced with bytes
|
|
10
|
+
* from stdin, so it lands on `'cli'`; the `'stdin'` stage is the implicit
|
|
11
|
+
* fallback an absent CLI value takes before env.
|
|
12
|
+
*/
|
|
13
|
+
declare const RESOLUTION_ORDER: readonly ["cli", "stdin", "env", "config", "prompt", "default"];
|
|
14
|
+
/** One stage of {@link RESOLUTION_ORDER}. */
|
|
15
|
+
type ResolutionStage = (typeof RESOLUTION_ORDER)[number];
|
|
16
|
+
/**
|
|
17
|
+
* One declared source of a flag or an arg.
|
|
18
|
+
*
|
|
19
|
+
* Every stage that carries raw text also carries the {@link SplitPolicy} that
|
|
20
|
+
* text decodes under, so a collection's per-source splitting is read off the
|
|
21
|
+
* binding of the stage that produced the value. A declared default is already
|
|
22
|
+
* the typed value and has nothing to split.
|
|
23
|
+
*/
|
|
24
|
+
type SourceBinding = {
|
|
25
|
+
readonly stage: "cli";
|
|
26
|
+
readonly split: SplitPolicy;
|
|
27
|
+
} | {
|
|
28
|
+
readonly stage: "stdin";
|
|
29
|
+
readonly when: StdinWhen;
|
|
30
|
+
readonly consume: StdinConsume;
|
|
31
|
+
readonly trim: boolean;
|
|
32
|
+
readonly split: SplitPolicy;
|
|
33
|
+
} | {
|
|
34
|
+
readonly stage: "env";
|
|
35
|
+
readonly envVar: string;
|
|
36
|
+
readonly split: SplitPolicy;
|
|
37
|
+
} | {
|
|
38
|
+
readonly stage: "config";
|
|
39
|
+
readonly configPath: string;
|
|
40
|
+
readonly split: SplitPolicy;
|
|
41
|
+
} | {
|
|
42
|
+
readonly stage: "prompt";
|
|
43
|
+
readonly prompt: PromptConfig;
|
|
44
|
+
readonly split: SplitPolicy;
|
|
45
|
+
} | {
|
|
46
|
+
readonly stage: "default";
|
|
47
|
+
readonly defaultValue: unknown;
|
|
48
|
+
};
|
|
49
|
+
/** The stdin source of an input, once {@link sourceBindings} has projected it. */
|
|
50
|
+
type StdinSourceBinding = Extract<SourceBinding, {
|
|
51
|
+
readonly stage: "stdin";
|
|
52
|
+
}>;
|
|
53
|
+
/** The interactive source of an input, once {@link sourceBindings} has projected it. */
|
|
54
|
+
type PromptSourceBinding = Extract<SourceBinding, {
|
|
55
|
+
readonly stage: "prompt";
|
|
56
|
+
}>;
|
|
57
|
+
/**
|
|
58
|
+
* The sources whose raw values a stage decodes.
|
|
59
|
+
*
|
|
60
|
+
* A CLI token is decoded at the parse boundary, and a default never decodes at
|
|
61
|
+
* all, so neither reaches the resolver's coercion pass.
|
|
62
|
+
*/
|
|
63
|
+
type DecodedSourceBinding = Exclude<SourceBinding, {
|
|
64
|
+
readonly stage: "cli";
|
|
65
|
+
} | {
|
|
66
|
+
readonly stage: "default";
|
|
67
|
+
}>;
|
|
68
|
+
/**
|
|
69
|
+
* Project a flag or arg schema onto its source axis.
|
|
70
|
+
*
|
|
71
|
+
* Every input accepts CLI input, so the list always opens with `'cli'`. The
|
|
72
|
+
* remaining entries appear in {@link RESOLUTION_ORDER} order, and only for the
|
|
73
|
+
* sources the schema actually declares. The resolver walks this list, so a
|
|
74
|
+
* source the list omits is a source no stage can produce.
|
|
75
|
+
*
|
|
76
|
+
* A config value is native when it is an array or an object, and a config
|
|
77
|
+
* string decodes under the environment policy, which is the delimited form a
|
|
78
|
+
* user would have typed. A prompt answer reads the same way.
|
|
79
|
+
*
|
|
80
|
+
* @param schema - The flag or arg schema to read.
|
|
81
|
+
* @returns The declared sources, ordered by precedence.
|
|
82
|
+
*/
|
|
83
|
+
declare function sourceBindings(schema: FlagSchema | ArgSchema): readonly SourceBinding[];
|
|
84
|
+
/**
|
|
85
|
+
* The stdin source of an input, or `undefined` when it declares none.
|
|
86
|
+
*
|
|
87
|
+
* @param bindings - One input's source list.
|
|
88
|
+
* @returns The stdin binding, when the list carries one.
|
|
89
|
+
*/
|
|
90
|
+
declare function stdinBindingOf(bindings: readonly SourceBinding[]): StdinSourceBinding | undefined;
|
|
91
|
+
/**
|
|
92
|
+
* The bindings an interactive resolver has not yet had a say in.
|
|
93
|
+
*
|
|
94
|
+
* @param bindings - One input's source list.
|
|
95
|
+
* @returns The entries ranked before `'prompt'`.
|
|
96
|
+
*/
|
|
97
|
+
declare function bindingsBeforePrompt(bindings: readonly SourceBinding[]): readonly SourceBinding[];
|
|
98
|
+
/**
|
|
99
|
+
* The bindings left once an interactive resolver has run.
|
|
100
|
+
*
|
|
101
|
+
* @param bindings - One input's source list.
|
|
102
|
+
* @returns The entries ranked at or after `'prompt'`.
|
|
103
|
+
*/
|
|
104
|
+
declare function bindingsFromPrompt(bindings: readonly SourceBinding[]): readonly SourceBinding[];
|
|
105
|
+
/**
|
|
106
|
+
* Replace the prompt binding with the config this invocation actually uses.
|
|
107
|
+
*
|
|
108
|
+
* `.interactive()` may hand a prompt to an input that declares none, or take
|
|
109
|
+
* away the one it declares, so the effective list is per invocation rather than
|
|
110
|
+
* per schema.
|
|
111
|
+
*
|
|
112
|
+
* @param schema - The flag or arg the list belongs to, read for its splitting.
|
|
113
|
+
* @param bindings - One input's source list.
|
|
114
|
+
* @param prompt - The prompt config to use, or `undefined` for no prompt.
|
|
115
|
+
* @returns The list with its prompt binding set to `prompt`.
|
|
116
|
+
*/
|
|
117
|
+
declare function withPromptBinding(schema: FlagSchema | ArgSchema, bindings: readonly SourceBinding[], prompt: PromptConfig | undefined): readonly SourceBinding[];
|
|
118
|
+
/** One stdin-enabled input of a command, named by the surface that declares it. */
|
|
119
|
+
interface StdinConsumer {
|
|
120
|
+
/** Which surface declares the input. */
|
|
121
|
+
readonly kind: "flag" | "arg";
|
|
122
|
+
/** Canonical flag name or positional arg name. */
|
|
123
|
+
readonly name: string;
|
|
124
|
+
/** The input's stdin axis. */
|
|
125
|
+
readonly stdin: StdinBinding;
|
|
126
|
+
}
|
|
127
|
+
/**
|
|
128
|
+
* List the stdin consumers declared across a command's flags and args.
|
|
129
|
+
*
|
|
130
|
+
* @param flags - The command's flag schemas keyed by name.
|
|
131
|
+
* @param args - The command's positional entries in declaration order.
|
|
132
|
+
* @returns Every stdin-enabled input, flags first, then args in declaration order.
|
|
133
|
+
*/
|
|
134
|
+
declare function stdinConsumers(flags: Readonly<Record<string, FlagSchema>>, args: readonly {
|
|
135
|
+
readonly name: string;
|
|
136
|
+
readonly schema: ArgSchema;
|
|
137
|
+
}[]): readonly StdinConsumer[];
|
|
138
|
+
/** How a stdin consumer is spelled on the command line: `--out` or `<out>`. */
|
|
139
|
+
declare function stdinConsumerReference(consumer: Pick<StdinConsumer, "kind" | "name">): string;
|
|
140
|
+
/** What a parser produced for one command, read structurally. */
|
|
141
|
+
interface ParsedInputs {
|
|
142
|
+
/** Flag values keyed by canonical flag name. */
|
|
143
|
+
readonly flags: Readonly<Record<string, unknown>>;
|
|
144
|
+
/** Positional values keyed by arg name. */
|
|
145
|
+
readonly args: Readonly<Record<string, unknown>>;
|
|
146
|
+
}
|
|
147
|
+
/**
|
|
148
|
+
* Whether this invocation will actually select a stdin source.
|
|
149
|
+
*
|
|
150
|
+
* A `'dash'` binding fires when its token is `-`. A `'missing'` binding fires
|
|
151
|
+
* when argv left the input absent; env, config, prompt, and default do not
|
|
152
|
+
* suppress it, because the stdin fallback outranks all four. Callers use this
|
|
153
|
+
* to decide whether reading the stream is warranted at all.
|
|
154
|
+
*
|
|
155
|
+
* @param flags - Declared flags keyed by canonical name.
|
|
156
|
+
* @param args - Declared positionals in CLI order.
|
|
157
|
+
* @param parsed - What the parser read off argv.
|
|
158
|
+
* @returns `true` when at least one input would read stdin.
|
|
159
|
+
*/
|
|
160
|
+
declare function invocationSelectsStdin(flags: Readonly<Record<string, FlagSchema>>, args: readonly {
|
|
161
|
+
readonly name: string;
|
|
162
|
+
readonly schema: ArgSchema;
|
|
163
|
+
}[], parsed: ParsedInputs): boolean;
|
|
164
|
+
/**
|
|
165
|
+
* Whether a variadic arg's parsed value means its tail collected nothing.
|
|
166
|
+
*
|
|
167
|
+
* A variadic arg always has a key in the parser's record, and an empty list is
|
|
168
|
+
* how it spells an empty tail, so an input that reads stdin when missing is
|
|
169
|
+
* still missing here.
|
|
170
|
+
*
|
|
171
|
+
* @param schema - The positional's schema.
|
|
172
|
+
* @param value - What the parser produced for it.
|
|
173
|
+
* @returns `true` when the tail took no token.
|
|
174
|
+
*/
|
|
175
|
+
declare function argCollectedNothing(schema: ArgSchema, value: unknown): boolean;
|
|
176
|
+
/** The stdin selector, which names a source rather than a value. */
|
|
177
|
+
declare const STDIN_SENTINEL = "-";
|
|
178
|
+
//#endregion
|
|
179
|
+
export { type DecodedSourceBinding, type ParsedInputs, type PromptSourceBinding, RESOLUTION_ORDER, type ResolutionStage, STDIN_SENTINEL, type SourceBinding, type StdinConsumer, type StdinSourceBinding, argCollectedNothing, bindingsBeforePrompt, bindingsFromPrompt, invocationSelectsStdin, sourceBindings, stdinBindingOf, stdinConsumerReference, stdinConsumers, withPromptBinding };
|