@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
package/src/core/schema/flag.ts
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* Flag schema builder with full type inference.
|
|
3
3
|
*
|
|
4
4
|
* Each factory (`flag.string()`, `flag.boolean()`, etc.) returns an immutable
|
|
5
|
-
*
|
|
5
|
+
* {@linkcode FlagBuilder} whose generic parameter tracks the value type and presence
|
|
6
6
|
* state. Chained modifiers (`.default()`, `.required()`, `.alias()`, …) return
|
|
7
7
|
* new builders with updated type-level and runtime state.
|
|
8
8
|
*
|
|
@@ -13,6 +13,9 @@ import type { PromptConfig } from './prompt.ts';
|
|
|
13
13
|
|
|
14
14
|
// --- Type-level configuration (phantom state tracked through the chain)
|
|
15
15
|
|
|
16
|
+
/** All flag presence states as a runtime array. */
|
|
17
|
+
const FLAG_PRESENCES = ['optional', 'required', 'defaulted'] as const;
|
|
18
|
+
|
|
16
19
|
/**
|
|
17
20
|
* Presence describes whether a flag value is guaranteed to exist when the
|
|
18
21
|
* action handler runs:
|
|
@@ -22,7 +25,7 @@ import type { PromptConfig } from './prompt.ts';
|
|
|
22
25
|
* - `'required'` — must be supplied; error if missing
|
|
23
26
|
* - `'defaulted'` — always present (falls back to default value)
|
|
24
27
|
*/
|
|
25
|
-
type FlagPresence =
|
|
28
|
+
type FlagPresence = (typeof FLAG_PRESENCES)[number];
|
|
26
29
|
|
|
27
30
|
/**
|
|
28
31
|
* Fallback behavior when an optional flag resolves no value from any source.
|
|
@@ -50,7 +53,7 @@ interface FlagConfig {
|
|
|
50
53
|
// --- Type-level helpers
|
|
51
54
|
|
|
52
55
|
/**
|
|
53
|
-
* Advanced type helper used by
|
|
56
|
+
* Advanced type helper used by {@linkcode FlagBuilder} modifiers to replace presence.
|
|
54
57
|
* Most consumers rely on inference and never reference this directly.
|
|
55
58
|
*/
|
|
56
59
|
type WithPresence<C extends FlagConfig, P extends FlagPresence> = {
|
|
@@ -76,7 +79,7 @@ type ResolvedValue<C extends FlagConfig> = C['presence'] extends 'optional'
|
|
|
76
79
|
: C['valueType'] | undefined
|
|
77
80
|
: C['valueType'];
|
|
78
81
|
|
|
79
|
-
/** Extract the resolved value type from a
|
|
82
|
+
/** Extract the resolved value type from a {@linkcode FlagBuilder}. */
|
|
80
83
|
type InferFlag<B> = B extends FlagBuilder<infer C extends FlagConfig> ? ResolvedValue<C> : never;
|
|
81
84
|
|
|
82
85
|
/** Extract resolved value types from a record of builders. */
|
|
@@ -86,8 +89,11 @@ type InferFlags<T extends Record<string, FlagBuilder<FlagConfig>>> = {
|
|
|
86
89
|
|
|
87
90
|
// --- Runtime schema data
|
|
88
91
|
|
|
92
|
+
/** All flag kind discriminators as a runtime array. */
|
|
93
|
+
const FLAG_KINDS = ['string', 'number', 'boolean', 'enum', 'array', 'custom'] as const;
|
|
94
|
+
|
|
89
95
|
/** Discriminator for the kind of value a flag accepts. */
|
|
90
|
-
type FlagKind =
|
|
96
|
+
type FlagKind = (typeof FLAG_KINDS)[number];
|
|
91
97
|
|
|
92
98
|
/**
|
|
93
99
|
* Custom parse function for `flag.custom()`.
|
|
@@ -97,8 +103,16 @@ type FlagKind = 'string' | 'number' | 'boolean' | 'enum' | 'array' | 'custom';
|
|
|
97
103
|
*/
|
|
98
104
|
type FlagParseFn<T> = (raw: unknown) => T;
|
|
99
105
|
|
|
106
|
+
/** Runtime descriptor for a flag alias. */
|
|
107
|
+
interface FlagAlias {
|
|
108
|
+
/** Alias name without `-` / `--` prefix. */
|
|
109
|
+
readonly name: string;
|
|
110
|
+
/** Whether the alias is parser-only and hidden from user-facing surfaces. */
|
|
111
|
+
readonly hidden: boolean;
|
|
112
|
+
}
|
|
113
|
+
|
|
100
114
|
/**
|
|
101
|
-
* The runtime descriptor stored inside every
|
|
115
|
+
* The runtime descriptor stored inside every {@linkcode FlagBuilder}. Consumers (parser,
|
|
102
116
|
* help generator, resolution chain) read this to understand the flag's shape
|
|
103
117
|
* without touching generics.
|
|
104
118
|
*/
|
|
@@ -109,8 +123,8 @@ interface FlagSchema {
|
|
|
109
123
|
readonly presence: FlagPresence;
|
|
110
124
|
/** Runtime default value (if any). */
|
|
111
125
|
readonly defaultValue: unknown;
|
|
112
|
-
/** Short/long aliases (e.g. `['f']` for `--force`). */
|
|
113
|
-
readonly aliases: readonly
|
|
126
|
+
/** Short/long aliases (e.g. `[{ name: 'f', hidden: false }]` for `--force`). */
|
|
127
|
+
readonly aliases: readonly FlagAlias[];
|
|
114
128
|
/** Environment variable name for v0.2+ resolution. */
|
|
115
129
|
readonly envVar: string | undefined;
|
|
116
130
|
/** Dotted config path for v0.2+ resolution (e.g. `'deploy.region'`). */
|
|
@@ -148,6 +162,70 @@ interface FlagSchema {
|
|
|
148
162
|
readonly propagate: boolean;
|
|
149
163
|
}
|
|
150
164
|
|
|
165
|
+
/**
|
|
166
|
+
* Low-level overrides accepted by {@link createSchema}.
|
|
167
|
+
*
|
|
168
|
+
* `aliases` accepts both legacy string input and structured {@link FlagAlias}
|
|
169
|
+
* objects so tests and internal fixtures can be migrated incrementally.
|
|
170
|
+
*/
|
|
171
|
+
type FlagSchemaOverrides = Omit<Partial<FlagSchema>, 'aliases'> & {
|
|
172
|
+
readonly aliases?: readonly (string | FlagAlias)[];
|
|
173
|
+
};
|
|
174
|
+
|
|
175
|
+
/**
|
|
176
|
+
* Normalise an alias input into a full {@link FlagAlias} object.
|
|
177
|
+
*
|
|
178
|
+
* @param alias - Raw alias name or structured alias object.
|
|
179
|
+
* @returns Normalised alias record.
|
|
180
|
+
*/
|
|
181
|
+
function normalizeFlagAlias(alias: string | FlagAlias): FlagAlias {
|
|
182
|
+
if (typeof alias === 'string') {
|
|
183
|
+
return { name: alias, hidden: false };
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
return {
|
|
187
|
+
name: alias.name,
|
|
188
|
+
hidden: alias.hidden,
|
|
189
|
+
};
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
/**
|
|
193
|
+
* Normalise alias input into immutable alias records.
|
|
194
|
+
*
|
|
195
|
+
* @param aliases - Alias input values.
|
|
196
|
+
* @returns Normalised alias objects.
|
|
197
|
+
*/
|
|
198
|
+
function normalizeFlagAliases(aliases: readonly (string | FlagAlias)[]): readonly FlagAlias[] {
|
|
199
|
+
return aliases.map(normalizeFlagAlias);
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
/**
|
|
203
|
+
* List alias names for a flag schema.
|
|
204
|
+
*
|
|
205
|
+
* @param schema - Flag schema whose aliases should be listed.
|
|
206
|
+
* @param options - Visibility and length filtering.
|
|
207
|
+
* @returns Alias names in registration order.
|
|
208
|
+
*/
|
|
209
|
+
function getFlagAliasNames(
|
|
210
|
+
schema: FlagSchema,
|
|
211
|
+
options?: {
|
|
212
|
+
readonly includeHidden?: boolean;
|
|
213
|
+
readonly kind?: 'all' | 'short' | 'long';
|
|
214
|
+
},
|
|
215
|
+
): readonly string[] {
|
|
216
|
+
const includeHidden = options?.includeHidden ?? false;
|
|
217
|
+
const kind = options?.kind ?? 'all';
|
|
218
|
+
|
|
219
|
+
return schema.aliases
|
|
220
|
+
.filter((alias) => includeHidden || !alias.hidden)
|
|
221
|
+
.filter((alias) => {
|
|
222
|
+
if (kind === 'short') return alias.name.length === 1;
|
|
223
|
+
if (kind === 'long') return alias.name.length > 1;
|
|
224
|
+
return true;
|
|
225
|
+
})
|
|
226
|
+
.map((alias) => alias.name);
|
|
227
|
+
}
|
|
228
|
+
|
|
151
229
|
/**
|
|
152
230
|
* Create a raw {@link FlagSchema} object with sensible defaults.
|
|
153
231
|
*
|
|
@@ -172,12 +250,15 @@ interface FlagSchema {
|
|
|
172
250
|
* });
|
|
173
251
|
* ```
|
|
174
252
|
*/
|
|
175
|
-
function createSchema(kind: FlagKind, overrides?:
|
|
253
|
+
function createSchema(kind: FlagKind, overrides?: FlagSchemaOverrides): FlagSchema {
|
|
254
|
+
const aliases =
|
|
255
|
+
overrides?.aliases !== undefined ? normalizeFlagAliases(overrides.aliases) : ([] as const);
|
|
256
|
+
const { aliases: _ignoredAliases, ...rest } = overrides ?? {};
|
|
257
|
+
|
|
176
258
|
return {
|
|
177
259
|
kind,
|
|
178
260
|
presence: 'optional',
|
|
179
261
|
defaultValue: undefined,
|
|
180
|
-
aliases: [],
|
|
181
262
|
envVar: undefined,
|
|
182
263
|
configPath: undefined,
|
|
183
264
|
description: undefined,
|
|
@@ -187,7 +268,8 @@ function createSchema(kind: FlagKind, overrides?: Partial<FlagSchema>): FlagSche
|
|
|
187
268
|
parseFn: undefined,
|
|
188
269
|
deprecated: undefined,
|
|
189
270
|
propagate: false,
|
|
190
|
-
...
|
|
271
|
+
...rest,
|
|
272
|
+
aliases,
|
|
191
273
|
};
|
|
192
274
|
}
|
|
193
275
|
|
|
@@ -215,11 +297,13 @@ class FlagBuilder<C extends FlagConfig> {
|
|
|
215
297
|
|
|
216
298
|
/**
|
|
217
299
|
* @internal Type brand — exists only in the type system (`declare`
|
|
218
|
-
* produces no runtime property). Used by
|
|
300
|
+
* produces no runtime property). Used by {@linkcode InferFlag} / {@linkcode InferFlags}.
|
|
219
301
|
*/
|
|
220
302
|
declare readonly _config: C;
|
|
221
303
|
|
|
222
304
|
/**
|
|
305
|
+
* Create a flag builder from a pre-built schema descriptor.
|
|
306
|
+
*
|
|
223
307
|
* @param schema - Runtime descriptor seeding this builder's state.
|
|
224
308
|
*/
|
|
225
309
|
constructor(schema: FlagSchema) {
|
|
@@ -284,6 +368,8 @@ class FlagBuilder<C extends FlagConfig> {
|
|
|
284
368
|
* alternative long name).
|
|
285
369
|
*
|
|
286
370
|
* @param name - Single-char short alias or alternative long name.
|
|
371
|
+
* @param options - Optional alias metadata. Hidden aliases remain parseable
|
|
372
|
+
* but are omitted from help, completions, and suggestions.
|
|
287
373
|
* @returns The builder (for chaining).
|
|
288
374
|
*
|
|
289
375
|
* @example
|
|
@@ -294,10 +380,16 @@ class FlagBuilder<C extends FlagConfig> {
|
|
|
294
380
|
* // $ mycli build --verbose → verbose = true
|
|
295
381
|
* ```
|
|
296
382
|
*/
|
|
297
|
-
alias(name: string): FlagBuilder<C> {
|
|
383
|
+
alias(name: string, options?: { hidden?: boolean }): FlagBuilder<C> {
|
|
298
384
|
return new FlagBuilder({
|
|
299
385
|
...this.schema,
|
|
300
|
-
aliases: [
|
|
386
|
+
aliases: [
|
|
387
|
+
...this.schema.aliases,
|
|
388
|
+
{
|
|
389
|
+
name,
|
|
390
|
+
hidden: options?.hidden ?? false,
|
|
391
|
+
},
|
|
392
|
+
],
|
|
301
393
|
});
|
|
302
394
|
}
|
|
303
395
|
|
|
@@ -636,16 +728,29 @@ export type {
|
|
|
636
728
|
SelectChoice,
|
|
637
729
|
SelectPromptConfig,
|
|
638
730
|
} from './prompt.ts';
|
|
731
|
+
export { PROMPT_KINDS } from './prompt.ts';
|
|
639
732
|
export type {
|
|
733
|
+
FlagAlias,
|
|
640
734
|
FlagConfig,
|
|
641
735
|
FlagFactory,
|
|
642
736
|
FlagKind,
|
|
643
737
|
FlagParseFn,
|
|
644
738
|
FlagPresence,
|
|
645
739
|
FlagSchema,
|
|
740
|
+
FlagSchemaOverrides,
|
|
646
741
|
InferFlag,
|
|
647
742
|
InferFlags,
|
|
743
|
+
OptionalFallback,
|
|
648
744
|
ResolvedValue,
|
|
649
745
|
WithPresence,
|
|
650
746
|
};
|
|
651
|
-
export {
|
|
747
|
+
export {
|
|
748
|
+
createSchema,
|
|
749
|
+
FLAG_KINDS,
|
|
750
|
+
FLAG_PRESENCES,
|
|
751
|
+
FlagBuilder,
|
|
752
|
+
flag,
|
|
753
|
+
getFlagAliasNames,
|
|
754
|
+
normalizeFlagAlias,
|
|
755
|
+
normalizeFlagAliases,
|
|
756
|
+
};
|
package/src/core/schema/index.ts
CHANGED
|
@@ -29,7 +29,7 @@ export type {
|
|
|
29
29
|
WithArgPresence,
|
|
30
30
|
WithVariadic,
|
|
31
31
|
} from './arg.ts';
|
|
32
|
-
export { ArgBuilder, arg, createArgSchema } from './arg.ts';
|
|
32
|
+
export { ARG_KINDS, ARG_PRESENCES, ArgBuilder, arg, createArgSchema } from './arg.ts';
|
|
33
33
|
export type {
|
|
34
34
|
ActionHandler,
|
|
35
35
|
ActionParams,
|
|
@@ -52,12 +52,14 @@ export type {
|
|
|
52
52
|
export { CommandBuilder, command, group } from './command.ts';
|
|
53
53
|
export type {
|
|
54
54
|
ConfirmPromptConfig,
|
|
55
|
+
FlagAlias,
|
|
55
56
|
FlagConfig,
|
|
56
57
|
FlagFactory,
|
|
57
58
|
FlagKind,
|
|
58
59
|
FlagParseFn,
|
|
59
60
|
FlagPresence,
|
|
60
61
|
FlagSchema,
|
|
62
|
+
FlagSchemaOverrides,
|
|
61
63
|
InferFlag,
|
|
62
64
|
InferFlags,
|
|
63
65
|
InputPromptConfig,
|
|
@@ -71,7 +73,14 @@ export type {
|
|
|
71
73
|
SelectPromptConfig,
|
|
72
74
|
WithPresence,
|
|
73
75
|
} from './flag.ts';
|
|
74
|
-
export {
|
|
76
|
+
export {
|
|
77
|
+
createSchema,
|
|
78
|
+
FLAG_KINDS,
|
|
79
|
+
FLAG_PRESENCES,
|
|
80
|
+
FlagBuilder,
|
|
81
|
+
flag,
|
|
82
|
+
PROMPT_KINDS,
|
|
83
|
+
} from './flag.ts';
|
|
75
84
|
export type {
|
|
76
85
|
ErasedMiddlewareHandler,
|
|
77
86
|
Middleware,
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
* - Short-circuit by throwing `CLIError` (or not calling `next`)
|
|
7
7
|
* - Wrap downstream execution (timing, logging) by awaiting `next()`
|
|
8
8
|
*
|
|
9
|
-
* The
|
|
9
|
+
* The {@linkcode Middleware} type uses a phantom generic to track what
|
|
10
10
|
* context properties this middleware adds. At runtime, middleware is
|
|
11
11
|
* type-erased — the phantom type is only used for compile-time inference
|
|
12
12
|
* when `.middleware()` is chained on `CommandBuilder`.
|
|
@@ -52,7 +52,7 @@ interface MiddlewareParams {
|
|
|
52
52
|
* Type-erased middleware handler stored on `CommandSchema`.
|
|
53
53
|
*
|
|
54
54
|
* At runtime, all middleware handlers have this signature. The phantom
|
|
55
|
-
* `Output` type on
|
|
55
|
+
* `Output` type on {@linkcode Middleware} is erased.
|
|
56
56
|
*
|
|
57
57
|
* @internal
|
|
58
58
|
*/
|
|
@@ -62,7 +62,7 @@ type ErasedMiddlewareHandler = (params: MiddlewareParams) => void | Promise<void
|
|
|
62
62
|
* Middleware handler function with typed `next()` parameter.
|
|
63
63
|
*
|
|
64
64
|
* The `Output` generic constrains what properties must be passed to
|
|
65
|
-
*
|
|
65
|
+
* {@linkcode MiddlewareParams.next | next()}, ensuring type-safe context additions at the call site.
|
|
66
66
|
*/
|
|
67
67
|
type MiddlewareHandler<Output extends Record<string, unknown>> = (params: {
|
|
68
68
|
readonly args: Readonly<Record<string, unknown>>;
|
|
@@ -91,7 +91,7 @@ interface MiddlewareImpl {
|
|
|
91
91
|
* compile time. The `_output` brand is phantom — it exists only in the
|
|
92
92
|
* type system for inference, not at runtime.
|
|
93
93
|
*
|
|
94
|
-
* Created via the
|
|
94
|
+
* Created via the {@linkcode middleware} factory. Attached to commands via
|
|
95
95
|
* `CommandBuilder.middleware()`.
|
|
96
96
|
*
|
|
97
97
|
* @example
|
|
@@ -118,10 +118,10 @@ type Middleware<Output extends Record<string, unknown>> = MiddlewareImpl & {
|
|
|
118
118
|
* Middleware runs before the action handler and can add typed context,
|
|
119
119
|
* short-circuit execution, or wrap downstream processing.
|
|
120
120
|
*
|
|
121
|
-
* @param handler - Function receiving `{ args, flags, ctx, out, next }`.
|
|
121
|
+
* @param handler - Function receiving `{ args, flags, ctx, out, meta, next }`.
|
|
122
122
|
* Call `next(additions)` to continue the chain with added context.
|
|
123
123
|
* Omitting the `next()` call short-circuits (e.g., for auth guards).
|
|
124
|
-
* @returns Middleware to attach via `CommandBuilder.middleware()`.
|
|
124
|
+
* @returns {@linkcode Middleware} to attach via `CommandBuilder.middleware()`.
|
|
125
125
|
*
|
|
126
126
|
* @example
|
|
127
127
|
* ```ts
|
|
@@ -11,6 +11,9 @@
|
|
|
11
11
|
|
|
12
12
|
// --- Prompt kind discriminator
|
|
13
13
|
|
|
14
|
+
/** All prompt kind discriminators as a runtime array. */
|
|
15
|
+
const PROMPT_KINDS = ['confirm', 'input', 'select', 'multiselect'] as const;
|
|
16
|
+
|
|
14
17
|
/**
|
|
15
18
|
* The kind of interactive prompt to present.
|
|
16
19
|
*
|
|
@@ -19,7 +22,7 @@
|
|
|
19
22
|
* - `'select'` — single selection from a list
|
|
20
23
|
* - `'multiselect'` — multiple selections from a list
|
|
21
24
|
*/
|
|
22
|
-
type PromptKind =
|
|
25
|
+
type PromptKind = (typeof PROMPT_KINDS)[number];
|
|
23
26
|
|
|
24
27
|
// --- Per-kind prompt configuration (discriminated union)
|
|
25
28
|
|
|
@@ -31,11 +34,13 @@ interface PromptConfigBase {
|
|
|
31
34
|
|
|
32
35
|
/** Yes/no confirmation prompt — maps to `boolean` flags. Part of {@link PromptConfig}. */
|
|
33
36
|
interface ConfirmPromptConfig extends PromptConfigBase {
|
|
37
|
+
/** Discriminator identifying this as a yes/no confirmation prompt. */
|
|
34
38
|
readonly kind: 'confirm';
|
|
35
39
|
}
|
|
36
40
|
|
|
37
41
|
/** Free-text input prompt — maps to `string` and `number` flags. Part of {@link PromptConfig}. */
|
|
38
42
|
interface InputPromptConfig extends PromptConfigBase {
|
|
43
|
+
/** Discriminator identifying this as a free-text input prompt. */
|
|
39
44
|
readonly kind: 'input';
|
|
40
45
|
/** Placeholder text shown before user types (informational only). */
|
|
41
46
|
readonly placeholder?: string;
|
|
@@ -48,6 +53,7 @@ interface InputPromptConfig extends PromptConfigBase {
|
|
|
48
53
|
|
|
49
54
|
/** Single-selection prompt — maps to `enum` flags or any flag with {@link SelectChoice choices}. Part of {@link PromptConfig}. */
|
|
50
55
|
interface SelectPromptConfig extends PromptConfigBase {
|
|
56
|
+
/** Discriminator identifying this as a single-selection prompt. */
|
|
51
57
|
readonly kind: 'select';
|
|
52
58
|
/**
|
|
53
59
|
* Available choices. When omitted for `enum` flags, the enum values
|
|
@@ -61,6 +67,7 @@ interface SelectPromptConfig extends PromptConfigBase {
|
|
|
61
67
|
* Returns an array of selected {@link SelectChoice} values. Part of {@link PromptConfig}.
|
|
62
68
|
*/
|
|
63
69
|
interface MultiselectPromptConfig extends PromptConfigBase {
|
|
70
|
+
/** Discriminator identifying this as a multi-selection prompt. */
|
|
64
71
|
readonly kind: 'multiselect';
|
|
65
72
|
/**
|
|
66
73
|
* Available choices. When omitted for `array` flags with enum elements,
|
|
@@ -146,3 +153,4 @@ export type {
|
|
|
146
153
|
SelectChoice,
|
|
147
154
|
SelectPromptConfig,
|
|
148
155
|
};
|
|
156
|
+
export { PROMPT_KINDS };
|
package/src/core/schema/run.ts
CHANGED
|
@@ -17,13 +17,13 @@ import type { ActivityEvent } from './activity.ts';
|
|
|
17
17
|
import type { CommandMeta, CommandSchema, Out } from './command.ts';
|
|
18
18
|
|
|
19
19
|
/**
|
|
20
|
-
* Options accepted by `
|
|
20
|
+
* Options accepted by `runCommand()` and internal command execution paths.
|
|
21
21
|
*
|
|
22
22
|
* Every field is optional — sensible defaults are applied. This is the
|
|
23
|
-
* primary execution seam: inject env, config, prompt I/O, and
|
|
24
|
-
* metadata without touching process state.
|
|
23
|
+
* primary process-free execution seam: inject env, config, prompt I/O, and
|
|
24
|
+
* dispatch-layer metadata without touching process state.
|
|
25
25
|
*/
|
|
26
|
-
interface RunOptions {
|
|
26
|
+
export interface RunOptions {
|
|
27
27
|
/**
|
|
28
28
|
* Environment variables for flag resolution.
|
|
29
29
|
*
|
|
@@ -82,8 +82,8 @@ interface RunOptions {
|
|
|
82
82
|
* Enable JSON output mode.
|
|
83
83
|
*
|
|
84
84
|
* When `true`, `log` and `info` messages are redirected to stderr
|
|
85
|
-
* so that stdout is reserved exclusively for structured
|
|
86
|
-
*
|
|
85
|
+
* so that stdout is reserved exclusively for structured {@linkcode Out.json | json()} output.
|
|
86
|
+
* Framework-rendered errors are emitted as structured JSON to stdout.
|
|
87
87
|
*
|
|
88
88
|
* @defaultValue `false`
|
|
89
89
|
*/
|
|
@@ -92,7 +92,7 @@ interface RunOptions {
|
|
|
92
92
|
/**
|
|
93
93
|
* Whether stdout is connected to a TTY.
|
|
94
94
|
*
|
|
95
|
-
* Handlers can check
|
|
95
|
+
* Handlers can check {@linkcode Out.isTTY | out.isTTY} to decide whether to emit decorative
|
|
96
96
|
* output (spinners, progress bars, ANSI codes). Defaults to `false`
|
|
97
97
|
* (safe default for tests — non-TTY until proven otherwise).
|
|
98
98
|
*
|
|
@@ -103,7 +103,7 @@ interface RunOptions {
|
|
|
103
103
|
/**
|
|
104
104
|
* Output channel override used by live CLI execution.
|
|
105
105
|
*
|
|
106
|
-
* @internal — `run()` passes a real output channel so activity renders to
|
|
106
|
+
* @internal — `CLIBuilder.run()` passes a real output channel so activity renders to
|
|
107
107
|
* the terminal instead of being captured.
|
|
108
108
|
*/
|
|
109
109
|
readonly out?: Out;
|
|
@@ -112,7 +112,7 @@ interface RunOptions {
|
|
|
112
112
|
* Capture buffers override paired with `out`.
|
|
113
113
|
*
|
|
114
114
|
* @internal — when omitted, `runCommand()` creates empty buffers for the
|
|
115
|
-
* returned
|
|
115
|
+
* returned {@linkcode RunResult} while writing directly to the provided `out`.
|
|
116
116
|
*/
|
|
117
117
|
readonly captured?: CapturedOutput;
|
|
118
118
|
|
|
@@ -153,12 +153,22 @@ interface RunOptions {
|
|
|
153
153
|
}
|
|
154
154
|
|
|
155
155
|
/**
|
|
156
|
-
* Structured result from
|
|
156
|
+
* Structured result from {@linkcode runCommand}.
|
|
157
157
|
*
|
|
158
|
-
* Contains the exit code, captured stdout/stderr output,
|
|
159
|
-
*
|
|
158
|
+
* Contains the exit code, captured stdout/stderr output, recorded
|
|
159
|
+
* {@linkcode ActivityEvent | activity events}, and an `error` field
|
|
160
|
+
* that is `undefined` on success and a {@linkcode CLIError} on failure.
|
|
161
|
+
*
|
|
162
|
+
* @example
|
|
163
|
+
* ```ts
|
|
164
|
+
* const result = await runCommand(greetCmd, ['World']);
|
|
165
|
+
*
|
|
166
|
+
* expect(result.exitCode).toBe(0);
|
|
167
|
+
* expect(result.stdout).toContain('Hello, World!');
|
|
168
|
+
* expect(result.error).toBeUndefined();
|
|
169
|
+
* ```
|
|
160
170
|
*/
|
|
161
|
-
interface RunResult {
|
|
171
|
+
export interface RunResult {
|
|
162
172
|
/** Process exit code. 0 = success. */
|
|
163
173
|
readonly exitCode: number;
|
|
164
174
|
|
|
@@ -172,16 +182,14 @@ interface RunResult {
|
|
|
172
182
|
* Captured spinner and progress lifecycle events.
|
|
173
183
|
*
|
|
174
184
|
* Recorded separately from stdout/stderr — handlers that call
|
|
175
|
-
*
|
|
185
|
+
* {@linkcode Out.spinner | out.spinner()} or {@linkcode Out.progress | out.progress()} produce events here, enabling
|
|
176
186
|
* targeted assertions on activity lifecycle without parsing text.
|
|
177
187
|
*/
|
|
178
188
|
readonly activity: readonly ActivityEvent[];
|
|
179
189
|
|
|
180
190
|
/**
|
|
181
191
|
* The error that caused a non-zero exit, or `undefined` on success.
|
|
182
|
-
*
|
|
192
|
+
* {@linkcode CLIError} instances are preserved; unknown errors are wrapped.
|
|
183
193
|
*/
|
|
184
194
|
readonly error: CLIError | undefined;
|
|
185
195
|
}
|
|
186
|
-
|
|
187
|
-
export type { RunOptions, RunResult };
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Schema DSL — single-source schema definitions with compile-time types
|
|
3
|
+
* and runtime AST.
|
|
4
|
+
*
|
|
5
|
+
* Define a schema once as a string literal. At compile time, the string is
|
|
6
|
+
* parsed into a TypeScript type via {@link Parse}. At runtime, the same
|
|
7
|
+
* string is parsed into an AST ({@link SchemaNode}) for validation,
|
|
8
|
+
* JSON Schema generation, and introspection.
|
|
9
|
+
*
|
|
10
|
+
* ```ts
|
|
11
|
+
* const user = schema('{ name: string; age: number; tags?: string[] }');
|
|
12
|
+
*
|
|
13
|
+
* // Compile-time: inferred as { name: string; age: number; tags?: string[] }
|
|
14
|
+
* const data = user.parse(jsonInput);
|
|
15
|
+
* data.name; // string
|
|
16
|
+
* data.age; // number
|
|
17
|
+
* ```
|
|
18
|
+
*
|
|
19
|
+
* @module dreamcli/core/schema-dsl
|
|
20
|
+
*/
|
|
21
|
+
|
|
22
|
+
import type { Parse } from './parse.ts';
|
|
23
|
+
import type { SchemaNode } from './runtime.ts';
|
|
24
|
+
import { parseSchema, validateNode } from './runtime.ts';
|
|
25
|
+
|
|
26
|
+
// === Schema definition ===
|
|
27
|
+
|
|
28
|
+
/** The result of calling {@link schema}. Bundles source, AST, guard, and parse. */
|
|
29
|
+
interface SchemaDefinition<T extends string> {
|
|
30
|
+
/** The original source string. */
|
|
31
|
+
readonly source: T;
|
|
32
|
+
/** Runtime AST parsed from the source. */
|
|
33
|
+
readonly ast: SchemaNode;
|
|
34
|
+
/**
|
|
35
|
+
* Type guard — returns `true` if `input` matches the schema.
|
|
36
|
+
* Narrows the type to `Parse<T>` in the true branch.
|
|
37
|
+
*/
|
|
38
|
+
guard(input: unknown): input is Parse<T>;
|
|
39
|
+
/**
|
|
40
|
+
* Parse and validate — returns the narrowed value or throws.
|
|
41
|
+
* @throws {TypeError} if the input does not match the schema.
|
|
42
|
+
*/
|
|
43
|
+
parse(input: unknown): Parse<T>;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* Define a schema from a string literal.
|
|
48
|
+
*
|
|
49
|
+
* @param source - Schema string (e.g. `"{ name: string; age: number }"`).
|
|
50
|
+
* @returns A {@link SchemaDefinition} with compile-time types and runtime validation.
|
|
51
|
+
*
|
|
52
|
+
* @example
|
|
53
|
+
* ```ts
|
|
54
|
+
* const user = schema('{ name: string; age: number; admin?: boolean }');
|
|
55
|
+
*
|
|
56
|
+
* // Type guard
|
|
57
|
+
* if (user.guard(input)) {
|
|
58
|
+
* input.name; // string
|
|
59
|
+
* }
|
|
60
|
+
*
|
|
61
|
+
* // Parse or throw
|
|
62
|
+
* const data = user.parse(input);
|
|
63
|
+
* data.age; // number
|
|
64
|
+
* ```
|
|
65
|
+
*/
|
|
66
|
+
function schema<T extends string>(source: T): SchemaDefinition<T> {
|
|
67
|
+
const ast = parseSchema(source);
|
|
68
|
+
|
|
69
|
+
function guard(input: unknown): input is Parse<T> {
|
|
70
|
+
return validateNode(ast, input);
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
function parse(input: unknown): Parse<T> {
|
|
74
|
+
if (!guard(input)) {
|
|
75
|
+
throw new TypeError(`Value does not match schema: ${source}`);
|
|
76
|
+
}
|
|
77
|
+
return input;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
return { source, ast, guard, parse };
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
// === Re-exports ===
|
|
84
|
+
|
|
85
|
+
export type { Parse } from './parse.ts';
|
|
86
|
+
export type {
|
|
87
|
+
ArrayNode,
|
|
88
|
+
BooleanNode,
|
|
89
|
+
IntegerNode,
|
|
90
|
+
LiteralFalseNode,
|
|
91
|
+
LiteralNullNode,
|
|
92
|
+
LiteralStringNode,
|
|
93
|
+
LiteralTrueNode,
|
|
94
|
+
LiteralUndefinedNode,
|
|
95
|
+
NeverNode,
|
|
96
|
+
NumberNode,
|
|
97
|
+
ObjectNode,
|
|
98
|
+
PropertyNode,
|
|
99
|
+
RecordNode,
|
|
100
|
+
RefNode,
|
|
101
|
+
SchemaNode,
|
|
102
|
+
StringNode,
|
|
103
|
+
UnionNode,
|
|
104
|
+
UnknownNode,
|
|
105
|
+
} from './runtime.ts';
|
|
106
|
+
export { parseSchema, validateNode } from './runtime.ts';
|
|
107
|
+
export { nodeToJsonSchema } from './to-json-schema.ts';
|
|
108
|
+
export type { SchemaDefinition };
|
|
109
|
+
export { schema };
|