@kjanat/dreamcli 0.0.0 → 1.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 +667 -0
- package/LICENSE +22 -0
- package/README.md +370 -0
- package/dist/adapter-B37d9oia.mjs +1 -0
- package/dist/adapter-CCSh5juX.cjs +1 -0
- package/dist/adapter-DIwO-q7K.d.mts +3447 -0
- package/dist/adapter-DQnxxLiE.d.cts +3447 -0
- package/dist/auto-5cjZaF9V.mjs +3 -0
- package/dist/auto-B0eSgoDw.cjs +3 -0
- package/dist/index.cjs +10 -0
- package/dist/index.d.cts +920 -0
- package/dist/index.d.mts +920 -0
- package/dist/index.mjs +10 -0
- package/dist/runtime.cjs +1 -0
- package/dist/runtime.d.cts +253 -0
- package/dist/runtime.d.mts +253 -0
- package/dist/runtime.mjs +1 -0
- package/dist/testkit-CEDYPvhF.mjs +14 -0
- package/dist/testkit-ClIKijxC.cjs +14 -0
- package/dist/testkit.cjs +1 -0
- package/dist/testkit.d.cts +25 -0
- package/dist/testkit.d.mts +25 -0
- package/dist/testkit.mjs +1 -0
- package/examples/basic.ts +33 -0
- package/examples/gh/package.json +48 -0
- package/examples/gh/src/commands/auth.ts +66 -0
- package/examples/gh/src/commands/issue.ts +120 -0
- package/examples/gh/src/commands/pr.ts +125 -0
- package/examples/gh/src/data/issues.yaml +5 -0
- package/examples/gh/src/data/issues.yaml.d.ts +17 -0
- package/examples/gh/src/data/pull-requests.yaml +7 -0
- package/examples/gh/src/data/pull-requests.yaml.d.ts +18 -0
- package/examples/gh/src/lib/auth.ts +37 -0
- package/examples/gh/src/lib/utils.ts +17 -0
- package/examples/gh/src/main.test.ts +306 -0
- package/examples/gh/src/main.ts +38 -0
- package/examples/gh/tsconfig.json +37 -0
- package/examples/interactive.ts +66 -0
- package/examples/json-mode.ts +93 -0
- package/examples/middleware.ts +71 -0
- package/examples/multi-command.ts +66 -0
- package/examples/spinner-progress.ts +49 -0
- package/examples/testing.ts +145 -0
- package/examples/tsconfig.json +17 -0
- package/package.json +123 -2
- package/src/core/cli/AGENTS.md +72 -0
- package/src/core/cli/dispatch.ts +282 -0
- package/src/core/cli/index.ts +1425 -0
- package/src/core/cli/plugin.ts +111 -0
- package/src/core/cli/propagate.ts +97 -0
- package/src/core/cli/root-help.ts +269 -0
- package/src/core/cli/root-surface.ts +74 -0
- package/src/core/completion/AGENTS.md +72 -0
- package/src/core/completion/completion-test-helpers.ts +48 -0
- package/src/core/completion/index.ts +82 -0
- package/src/core/completion/shells/bash.ts +456 -0
- package/src/core/completion/shells/fish.ts +24 -0
- package/src/core/completion/shells/powershell.ts +24 -0
- package/src/core/completion/shells/shared.ts +283 -0
- package/src/core/completion/shells/zsh.ts +376 -0
- package/src/core/config/index.ts +404 -0
- package/src/core/config/package-json.ts +216 -0
- package/src/core/errors/index.ts +178 -0
- package/src/core/help/index.ts +559 -0
- package/src/core/json-schema/index.ts +705 -0
- package/src/core/output/AGENTS.md +69 -0
- package/src/core/output/activity.ts +568 -0
- package/src/core/output/display-value.ts +48 -0
- package/src/core/output/index.ts +704 -0
- package/src/core/output/writer.ts +46 -0
- package/src/core/parse/index.ts +643 -0
- package/src/core/prompt/index.ts +566 -0
- package/src/core/resolve/AGENTS.md +69 -0
- package/src/core/resolve/index.ts +1331 -0
- package/src/core/schema/AGENTS.md +61 -0
- package/src/core/schema/activity.ts +237 -0
- package/src/core/schema/arg.ts +707 -0
- package/src/core/schema/command.ts +1263 -0
- package/src/core/schema/flag.ts +651 -0
- package/src/core/schema/index.ts +82 -0
- package/src/core/schema/middleware.ts +171 -0
- package/src/core/schema/prompt.ts +148 -0
- package/src/core/schema/run.ts +187 -0
- package/src/core/testkit/AGENTS.md +55 -0
- package/src/core/testkit/index.ts +365 -0
- package/src/index.ts +164 -0
- package/src/runtime/AGENTS.md +74 -0
- package/src/runtime/adapter.ts +300 -0
- package/src/runtime/auto.ts +110 -0
- package/src/runtime/bun.ts +55 -0
- package/src/runtime/deno.ts +355 -0
- package/src/runtime/detect.ts +102 -0
- package/src/runtime/index.ts +21 -0
- package/src/runtime/node-builtins.d.ts +23 -0
- package/src/runtime/node.ts +278 -0
- package/src/runtime/paths.ts +56 -0
- package/src/runtime/support.ts +119 -0
- package/src/runtime/test-helpers.ts +40 -0
- package/src/runtime.ts +31 -0
- package/src/testkit.ts +23 -0
- package/src/version.ts +20 -0
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Command, flag, and arg schema builders with full type inference.
|
|
3
|
+
*
|
|
4
|
+
* @module dreamcli/core/schema
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
export type {
|
|
8
|
+
ActivityEvent,
|
|
9
|
+
Fallback,
|
|
10
|
+
ProgressHandle,
|
|
11
|
+
ProgressOptions,
|
|
12
|
+
SpinnerHandle,
|
|
13
|
+
SpinnerOptions,
|
|
14
|
+
TableColumn,
|
|
15
|
+
TableFormat,
|
|
16
|
+
TableOptions,
|
|
17
|
+
TableStream,
|
|
18
|
+
} from './activity.ts';
|
|
19
|
+
export type {
|
|
20
|
+
ArgConfig,
|
|
21
|
+
ArgFactory,
|
|
22
|
+
ArgKind,
|
|
23
|
+
ArgParseFn,
|
|
24
|
+
ArgPresence,
|
|
25
|
+
ArgSchema,
|
|
26
|
+
InferArg,
|
|
27
|
+
InferArgs,
|
|
28
|
+
ResolvedArgValue,
|
|
29
|
+
WithArgPresence,
|
|
30
|
+
WithVariadic,
|
|
31
|
+
} from './arg.ts';
|
|
32
|
+
export { ArgBuilder, arg, createArgSchema } from './arg.ts';
|
|
33
|
+
export type {
|
|
34
|
+
ActionHandler,
|
|
35
|
+
ActionParams,
|
|
36
|
+
AnyCommandBuilder,
|
|
37
|
+
CommandArgEntry,
|
|
38
|
+
CommandConfig,
|
|
39
|
+
CommandExample,
|
|
40
|
+
CommandMeta,
|
|
41
|
+
CommandSchema,
|
|
42
|
+
DeriveHandler,
|
|
43
|
+
DeriveParams,
|
|
44
|
+
ErasedCommand,
|
|
45
|
+
ErasedDeriveHandler,
|
|
46
|
+
ErasedInteractiveResolver,
|
|
47
|
+
InteractiveParams,
|
|
48
|
+
InteractiveResolver,
|
|
49
|
+
InteractiveResult,
|
|
50
|
+
Out,
|
|
51
|
+
} from './command.ts';
|
|
52
|
+
export { CommandBuilder, command, group } from './command.ts';
|
|
53
|
+
export type {
|
|
54
|
+
ConfirmPromptConfig,
|
|
55
|
+
FlagConfig,
|
|
56
|
+
FlagFactory,
|
|
57
|
+
FlagKind,
|
|
58
|
+
FlagParseFn,
|
|
59
|
+
FlagPresence,
|
|
60
|
+
FlagSchema,
|
|
61
|
+
InferFlag,
|
|
62
|
+
InferFlags,
|
|
63
|
+
InputPromptConfig,
|
|
64
|
+
MultiselectPromptConfig,
|
|
65
|
+
PromptConfig,
|
|
66
|
+
PromptConfigBase,
|
|
67
|
+
PromptKind,
|
|
68
|
+
PromptResult,
|
|
69
|
+
ResolvedValue,
|
|
70
|
+
SelectChoice,
|
|
71
|
+
SelectPromptConfig,
|
|
72
|
+
WithPresence,
|
|
73
|
+
} from './flag.ts';
|
|
74
|
+
export { createSchema, FlagBuilder, flag } from './flag.ts';
|
|
75
|
+
export type {
|
|
76
|
+
ErasedMiddlewareHandler,
|
|
77
|
+
Middleware,
|
|
78
|
+
MiddlewareHandler,
|
|
79
|
+
MiddlewareParams,
|
|
80
|
+
} from './middleware.ts';
|
|
81
|
+
export { middleware } from './middleware.ts';
|
|
82
|
+
export type { RunOptions, RunResult } from './run.ts';
|
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Middleware type definitions and factory function.
|
|
3
|
+
*
|
|
4
|
+
* Middleware runs before the action handler and can:
|
|
5
|
+
* - Add typed context via `next({ key: value })`
|
|
6
|
+
* - Short-circuit by throwing `CLIError` (or not calling `next`)
|
|
7
|
+
* - Wrap downstream execution (timing, logging) by awaiting `next()`
|
|
8
|
+
*
|
|
9
|
+
* The `Middleware<Output>` type uses a phantom generic to track what
|
|
10
|
+
* context properties this middleware adds. At runtime, middleware is
|
|
11
|
+
* type-erased — the phantom type is only used for compile-time inference
|
|
12
|
+
* when `.middleware()` is chained on `CommandBuilder`.
|
|
13
|
+
*
|
|
14
|
+
* @module dreamcli/core/schema/middleware
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
import type { CommandMeta, Out } from './command.ts';
|
|
18
|
+
|
|
19
|
+
// --- Middleware parameter types
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* Parameters received by a middleware function at runtime.
|
|
23
|
+
*
|
|
24
|
+
* Middleware receives erased args/flags (since it's defined independently
|
|
25
|
+
* of commands) plus the accumulated context from prior middleware and a
|
|
26
|
+
* `next` function to continue the chain.
|
|
27
|
+
*/
|
|
28
|
+
interface MiddlewareParams {
|
|
29
|
+
/** Fully resolved positional arguments (type-erased). */
|
|
30
|
+
readonly args: Readonly<Record<string, unknown>>;
|
|
31
|
+
/** Fully resolved flags (type-erased). */
|
|
32
|
+
readonly flags: Readonly<Record<string, unknown>>;
|
|
33
|
+
/** Context accumulated from previous middleware in the chain. */
|
|
34
|
+
readonly ctx: Readonly<Record<string, unknown>>;
|
|
35
|
+
/** Output channel. */
|
|
36
|
+
readonly out: Out;
|
|
37
|
+
/** CLI program metadata (name, bin, version, command). */
|
|
38
|
+
readonly meta: CommandMeta;
|
|
39
|
+
/**
|
|
40
|
+
* Continue to the next middleware or action handler.
|
|
41
|
+
*
|
|
42
|
+
* Call with context additions that merge into `ctx` for downstream.
|
|
43
|
+
* Returns when the entire downstream chain completes — enabling
|
|
44
|
+
* wrap-around patterns (timing, try/catch, cleanup).
|
|
45
|
+
*/
|
|
46
|
+
readonly next: (additions: Record<string, unknown>) => Promise<void>;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
// --- Handler types
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* Type-erased middleware handler stored on `CommandSchema`.
|
|
53
|
+
*
|
|
54
|
+
* At runtime, all middleware handlers have this signature. The phantom
|
|
55
|
+
* `Output` type on `Middleware<O>` is erased.
|
|
56
|
+
*
|
|
57
|
+
* @internal
|
|
58
|
+
*/
|
|
59
|
+
type ErasedMiddlewareHandler = (params: MiddlewareParams) => void | Promise<void>;
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* Middleware handler function with typed `next()` parameter.
|
|
63
|
+
*
|
|
64
|
+
* The `Output` generic constrains what properties must be passed to
|
|
65
|
+
* `next()`, ensuring type-safe context additions at the call site.
|
|
66
|
+
*/
|
|
67
|
+
type MiddlewareHandler<Output extends Record<string, unknown>> = (params: {
|
|
68
|
+
readonly args: Readonly<Record<string, unknown>>;
|
|
69
|
+
readonly flags: Readonly<Record<string, unknown>>;
|
|
70
|
+
readonly ctx: Readonly<Record<string, unknown>>;
|
|
71
|
+
readonly out: Out;
|
|
72
|
+
readonly meta: CommandMeta;
|
|
73
|
+
/** Pass context additions downstream. Must include all `Output` properties. */
|
|
74
|
+
readonly next: (additions: Output) => Promise<void>;
|
|
75
|
+
}) => void | Promise<void>;
|
|
76
|
+
|
|
77
|
+
// --- Middleware type — phantom-branded
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* Internal runtime representation of middleware.
|
|
81
|
+
* @internal
|
|
82
|
+
*/
|
|
83
|
+
interface MiddlewareImpl {
|
|
84
|
+
readonly _handler: ErasedMiddlewareHandler;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* Middleware with phantom output type.
|
|
89
|
+
*
|
|
90
|
+
* The `Output` parameter tracks what this middleware adds to context at
|
|
91
|
+
* compile time. The `_output` brand is phantom — it exists only in the
|
|
92
|
+
* type system for inference, not at runtime.
|
|
93
|
+
*
|
|
94
|
+
* Created via the `middleware()` factory. Attached to commands via
|
|
95
|
+
* `CommandBuilder.middleware()`.
|
|
96
|
+
*
|
|
97
|
+
* @example
|
|
98
|
+
* ```ts
|
|
99
|
+
* interface User { id: string; name: string }
|
|
100
|
+
*
|
|
101
|
+
* const auth = middleware<{ user: User }>(async ({ next }) => {
|
|
102
|
+
* const user = await getUser();
|
|
103
|
+
* if (!user) throw new CLIError('Not authenticated', { code: 'AUTH_REQUIRED' });
|
|
104
|
+
* return next({ user });
|
|
105
|
+
* });
|
|
106
|
+
* ```
|
|
107
|
+
*/
|
|
108
|
+
type Middleware<Output extends Record<string, unknown>> = MiddlewareImpl & {
|
|
109
|
+
/** @internal Phantom type brand — compile-time only. */
|
|
110
|
+
readonly _output: Output;
|
|
111
|
+
};
|
|
112
|
+
|
|
113
|
+
// --- Factory
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* Create a middleware definition.
|
|
117
|
+
*
|
|
118
|
+
* Middleware runs before the action handler and can add typed context,
|
|
119
|
+
* short-circuit execution, or wrap downstream processing.
|
|
120
|
+
*
|
|
121
|
+
* @param handler - Function receiving `{ args, flags, ctx, out, next }`.
|
|
122
|
+
* Call `next(additions)` to continue the chain with added context.
|
|
123
|
+
* Omitting the `next()` call short-circuits (e.g., for auth guards).
|
|
124
|
+
* @returns Middleware to attach via `CommandBuilder.middleware()`.
|
|
125
|
+
*
|
|
126
|
+
* @example
|
|
127
|
+
* ```ts
|
|
128
|
+
* // Auth guard — adds user to context or throws
|
|
129
|
+
* const auth = middleware(async ({ next }) => {
|
|
130
|
+
* const user = await getUser();
|
|
131
|
+
* if (!user) throw new CLIError('Not authenticated', { code: 'AUTH_REQUIRED' });
|
|
132
|
+
* return next({ user });
|
|
133
|
+
* });
|
|
134
|
+
*
|
|
135
|
+
* // Timing wrapper — measures downstream execution
|
|
136
|
+
* const timing = middleware(async ({ out, next }) => {
|
|
137
|
+
* const start = Date.now();
|
|
138
|
+
* await next({});
|
|
139
|
+
* out.info(`Done in ${Date.now() - start}ms`);
|
|
140
|
+
* });
|
|
141
|
+
*
|
|
142
|
+
* command('deploy')
|
|
143
|
+
* .middleware(timing)
|
|
144
|
+
* .middleware(auth)
|
|
145
|
+
* .action(({ ctx }) => {
|
|
146
|
+
* console.log(ctx.user.name); // typed!
|
|
147
|
+
* });
|
|
148
|
+
* ```
|
|
149
|
+
*/
|
|
150
|
+
function middleware<Output extends Record<string, unknown>>(
|
|
151
|
+
handler: MiddlewareHandler<Output>,
|
|
152
|
+
): Middleware<Output> {
|
|
153
|
+
// Runtime representation is just { _handler }.
|
|
154
|
+
// The type assertion establishes the phantom _output brand —
|
|
155
|
+
// no runtime property is created. handler's Output-constrained
|
|
156
|
+
// next() is compatible with the erased (Record<string, unknown>)
|
|
157
|
+
// signature at runtime.
|
|
158
|
+
const impl: MiddlewareImpl = { _handler: handler as ErasedMiddlewareHandler };
|
|
159
|
+
return impl as Middleware<Output>;
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
// --- Exports
|
|
163
|
+
|
|
164
|
+
export type {
|
|
165
|
+
ErasedMiddlewareHandler,
|
|
166
|
+
Middleware,
|
|
167
|
+
MiddlewareHandler,
|
|
168
|
+
MiddlewareImpl,
|
|
169
|
+
MiddlewareParams,
|
|
170
|
+
};
|
|
171
|
+
export { middleware };
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Prompt type definitions for interactive flag resolution.
|
|
3
|
+
*
|
|
4
|
+
* Prompt configuration is stored on `FlagSchema.prompt` and consumed by the
|
|
5
|
+
* resolution chain (v0.3+) when a flag value is missing after CLI/env/config
|
|
6
|
+
* resolution. The prompt engine reads this config to present the appropriate
|
|
7
|
+
* UI to the user.
|
|
8
|
+
*
|
|
9
|
+
* @module dreamcli/core/schema/prompt
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
// --- Prompt kind discriminator
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* The kind of interactive prompt to present.
|
|
16
|
+
*
|
|
17
|
+
* - `'confirm'` — yes/no boolean question
|
|
18
|
+
* - `'input'` — free-text string input
|
|
19
|
+
* - `'select'` — single selection from a list
|
|
20
|
+
* - `'multiselect'` — multiple selections from a list
|
|
21
|
+
*/
|
|
22
|
+
type PromptKind = 'confirm' | 'input' | 'select' | 'multiselect';
|
|
23
|
+
|
|
24
|
+
// --- Per-kind prompt configuration (discriminated union)
|
|
25
|
+
|
|
26
|
+
/** Shared fields across all prompt kinds. */
|
|
27
|
+
interface PromptConfigBase {
|
|
28
|
+
/** The question displayed to the user. */
|
|
29
|
+
readonly message: string;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** Yes/no confirmation prompt — maps to `boolean` flags. Part of {@link PromptConfig}. */
|
|
33
|
+
interface ConfirmPromptConfig extends PromptConfigBase {
|
|
34
|
+
readonly kind: 'confirm';
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** Free-text input prompt — maps to `string` and `number` flags. Part of {@link PromptConfig}. */
|
|
38
|
+
interface InputPromptConfig extends PromptConfigBase {
|
|
39
|
+
readonly kind: 'input';
|
|
40
|
+
/** Placeholder text shown before user types (informational only). */
|
|
41
|
+
readonly placeholder?: string;
|
|
42
|
+
/**
|
|
43
|
+
* Inline validation function. Return `true` if valid, or a string
|
|
44
|
+
* error message if invalid. Called before coercion to flag kind.
|
|
45
|
+
*/
|
|
46
|
+
readonly validate?: (value: string) => true | string;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/** Single-selection prompt — maps to `enum` flags or any flag with {@link SelectChoice choices}. Part of {@link PromptConfig}. */
|
|
50
|
+
interface SelectPromptConfig extends PromptConfigBase {
|
|
51
|
+
readonly kind: 'select';
|
|
52
|
+
/**
|
|
53
|
+
* Available choices. When omitted for `enum` flags, the enum values
|
|
54
|
+
* from the flag schema are used automatically.
|
|
55
|
+
*/
|
|
56
|
+
readonly choices?: readonly SelectChoice[];
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* Multi-selection prompt — maps to `array` flags.
|
|
61
|
+
* Returns an array of selected {@link SelectChoice} values. Part of {@link PromptConfig}.
|
|
62
|
+
*/
|
|
63
|
+
interface MultiselectPromptConfig extends PromptConfigBase {
|
|
64
|
+
readonly kind: 'multiselect';
|
|
65
|
+
/**
|
|
66
|
+
* Available choices. When omitted for `array` flags with enum elements,
|
|
67
|
+
* the enum values from the element schema are used automatically.
|
|
68
|
+
*/
|
|
69
|
+
readonly choices?: readonly SelectChoice[];
|
|
70
|
+
/**
|
|
71
|
+
* Minimum number of selections required.
|
|
72
|
+
* @defaultValue `0`
|
|
73
|
+
*/
|
|
74
|
+
readonly min?: number;
|
|
75
|
+
/**
|
|
76
|
+
* Maximum number of selections allowed.
|
|
77
|
+
* @defaultValue `Infinity`
|
|
78
|
+
*/
|
|
79
|
+
readonly max?: number;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
// --- Supporting types
|
|
83
|
+
|
|
84
|
+
/** A selectable option for {@link SelectPromptConfig} and {@link MultiselectPromptConfig} prompts. */
|
|
85
|
+
interface SelectChoice {
|
|
86
|
+
/** The value returned when this choice is selected. */
|
|
87
|
+
readonly value: string;
|
|
88
|
+
/**
|
|
89
|
+
* Display label shown to the user.
|
|
90
|
+
* @defaultValue {@link SelectChoice.value | value}
|
|
91
|
+
*/
|
|
92
|
+
readonly label?: string;
|
|
93
|
+
/** Optional description shown alongside the choice. */
|
|
94
|
+
readonly description?: string;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* Discriminated union of all prompt configurations.
|
|
99
|
+
*
|
|
100
|
+
* Use the `kind` field to narrow:
|
|
101
|
+
* ```ts
|
|
102
|
+
* if (config.kind === 'select') {
|
|
103
|
+
* config.choices // readonly SelectChoice[] | undefined
|
|
104
|
+
* }
|
|
105
|
+
* ```
|
|
106
|
+
*/
|
|
107
|
+
type PromptConfig =
|
|
108
|
+
| ConfirmPromptConfig
|
|
109
|
+
| InputPromptConfig
|
|
110
|
+
| SelectPromptConfig
|
|
111
|
+
| MultiselectPromptConfig;
|
|
112
|
+
|
|
113
|
+
// --- Prompt result
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* The raw result returned by a prompt engine for a single prompt.
|
|
117
|
+
*
|
|
118
|
+
* - `answered: true` — user provided a value
|
|
119
|
+
* - `answered: false` — user cancelled/aborted (Ctrl+C, ESC, etc.)
|
|
120
|
+
*
|
|
121
|
+
* Coercion to the flag's kind is the resolver's responsibility, not the
|
|
122
|
+
* prompt engine's.
|
|
123
|
+
*/
|
|
124
|
+
type PromptResult =
|
|
125
|
+
| {
|
|
126
|
+
/** User provided a value. */
|
|
127
|
+
readonly answered: true;
|
|
128
|
+
/** The raw value from the prompt engine (not yet coerced). */
|
|
129
|
+
readonly value: unknown;
|
|
130
|
+
}
|
|
131
|
+
| {
|
|
132
|
+
/** User cancelled or aborted (Ctrl+C, ESC, etc.). */
|
|
133
|
+
readonly answered: false;
|
|
134
|
+
};
|
|
135
|
+
|
|
136
|
+
// --- Exports
|
|
137
|
+
|
|
138
|
+
export type {
|
|
139
|
+
ConfirmPromptConfig,
|
|
140
|
+
InputPromptConfig,
|
|
141
|
+
MultiselectPromptConfig,
|
|
142
|
+
PromptConfig,
|
|
143
|
+
PromptConfigBase,
|
|
144
|
+
PromptKind,
|
|
145
|
+
PromptResult,
|
|
146
|
+
SelectChoice,
|
|
147
|
+
SelectPromptConfig,
|
|
148
|
+
};
|
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Run result type — structured output from command execution.
|
|
3
|
+
*
|
|
4
|
+
* Lives in schema (not testkit) because it describes the execution contract
|
|
5
|
+
* that `ErasedCommand._execute` returns. Both schema and testkit layers
|
|
6
|
+
* reference it without dependency inversion.
|
|
7
|
+
*
|
|
8
|
+
* @module dreamcli/core/schema/run
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
import type { CLIPlugin } from '#internals/core/cli/plugin.ts';
|
|
12
|
+
import type { CLIError } from '#internals/core/errors/index.ts';
|
|
13
|
+
import type { HelpOptions } from '#internals/core/help/index.ts';
|
|
14
|
+
import type { CapturedOutput, Verbosity } from '#internals/core/output/index.ts';
|
|
15
|
+
import type { PromptEngine, TestAnswer } from '#internals/core/prompt/index.ts';
|
|
16
|
+
import type { ActivityEvent } from './activity.ts';
|
|
17
|
+
import type { CommandMeta, CommandSchema, Out } from './command.ts';
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* Options accepted by `commandBuilder.run()` and `runCommand()`.
|
|
21
|
+
*
|
|
22
|
+
* Every field is optional — sensible defaults are applied. This is the
|
|
23
|
+
* primary execution seam: inject env, config, prompt I/O, and dispatch-layer
|
|
24
|
+
* metadata without touching process state.
|
|
25
|
+
*/
|
|
26
|
+
interface RunOptions {
|
|
27
|
+
/**
|
|
28
|
+
* Environment variables for flag resolution.
|
|
29
|
+
*
|
|
30
|
+
* Flags with `.env('VAR')` configured resolve from this record
|
|
31
|
+
* when no CLI value is provided (CLI → env → config → prompt → default).
|
|
32
|
+
*/
|
|
33
|
+
readonly env?: Readonly<Record<string, string | undefined>>;
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Configuration object for flag resolution.
|
|
37
|
+
*
|
|
38
|
+
* Flags with `.config('path')` configured resolve from this record
|
|
39
|
+
* when no CLI or env value is provided (CLI → env → config → prompt → default).
|
|
40
|
+
* Config is plain JSON — file loading is the caller's responsibility.
|
|
41
|
+
*/
|
|
42
|
+
readonly config?: Readonly<Record<string, unknown>>;
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* Full stdin contents for args configured with `.stdin()`.
|
|
46
|
+
*
|
|
47
|
+
* Lets tests inject piped input without a runtime adapter.
|
|
48
|
+
*/
|
|
49
|
+
readonly stdinData?: string | null;
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* Prompt engine for interactive flag resolution.
|
|
53
|
+
*
|
|
54
|
+
* When provided, flags with `.prompt()` configured that have no value
|
|
55
|
+
* after CLI/env/config resolution will be prompted interactively.
|
|
56
|
+
*
|
|
57
|
+
* When absent (and `answers` is also absent), prompting is skipped
|
|
58
|
+
* and resolution falls through to default/required.
|
|
59
|
+
*
|
|
60
|
+
* Takes precedence over `answers` when both are provided.
|
|
61
|
+
*/
|
|
62
|
+
readonly prompter?: PromptEngine;
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* Pre-configured prompt answers for testing convenience.
|
|
66
|
+
*
|
|
67
|
+
* When provided, a test prompter is created from these answers via
|
|
68
|
+
* `createTestPrompter(answers)`. Each entry is consumed in order —
|
|
69
|
+
* use `PROMPT_CANCEL` to simulate cancellation.
|
|
70
|
+
*
|
|
71
|
+
* Ignored when an explicit `prompter` is provided.
|
|
72
|
+
*/
|
|
73
|
+
readonly answers?: readonly TestAnswer[];
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* Verbosity level for the output channel.
|
|
77
|
+
* @defaultValue `'normal'`
|
|
78
|
+
*/
|
|
79
|
+
readonly verbosity?: Verbosity;
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* Enable JSON output mode.
|
|
83
|
+
*
|
|
84
|
+
* When `true`, `log` and `info` messages are redirected to stderr
|
|
85
|
+
* so that stdout is reserved exclusively for structured `json()` output.
|
|
86
|
+
* Errors are also rendered as JSON to stderr.
|
|
87
|
+
*
|
|
88
|
+
* @defaultValue `false`
|
|
89
|
+
*/
|
|
90
|
+
readonly jsonMode?: boolean;
|
|
91
|
+
|
|
92
|
+
/**
|
|
93
|
+
* Whether stdout is connected to a TTY.
|
|
94
|
+
*
|
|
95
|
+
* Handlers can check `out.isTTY` to decide whether to emit decorative
|
|
96
|
+
* output (spinners, progress bars, ANSI codes). Defaults to `false`
|
|
97
|
+
* (safe default for tests — non-TTY until proven otherwise).
|
|
98
|
+
*
|
|
99
|
+
* @defaultValue `false`
|
|
100
|
+
*/
|
|
101
|
+
readonly isTTY?: boolean;
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* Output channel override used by live CLI execution.
|
|
105
|
+
*
|
|
106
|
+
* @internal — `run()` passes a real output channel so activity renders to
|
|
107
|
+
* the terminal instead of being captured.
|
|
108
|
+
*/
|
|
109
|
+
readonly out?: Out;
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* Capture buffers override paired with `out`.
|
|
113
|
+
*
|
|
114
|
+
* @internal — when omitted, `runCommand()` creates empty buffers for the
|
|
115
|
+
* returned `RunResult` while writing directly to the provided `out`.
|
|
116
|
+
*/
|
|
117
|
+
readonly captured?: CapturedOutput;
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* Help formatting options (width, binName).
|
|
121
|
+
* Used when `--help` is detected.
|
|
122
|
+
*/
|
|
123
|
+
readonly help?: HelpOptions;
|
|
124
|
+
|
|
125
|
+
/**
|
|
126
|
+
* Command schema with propagated flags merged in.
|
|
127
|
+
*
|
|
128
|
+
* When provided, used for parsing and resolution instead of `cmd.schema`.
|
|
129
|
+
* Set by the CLI dispatch layer after collecting propagated flags from
|
|
130
|
+
* the command ancestry path.
|
|
131
|
+
*
|
|
132
|
+
* @internal — set by dispatch layer, not for public use.
|
|
133
|
+
*/
|
|
134
|
+
readonly mergedSchema?: CommandSchema;
|
|
135
|
+
|
|
136
|
+
/**
|
|
137
|
+
* CLI program metadata passed to action handlers and middleware.
|
|
138
|
+
*
|
|
139
|
+
* When provided (by CLI dispatch layer), handlers receive this as `meta`.
|
|
140
|
+
* When absent (standalone `runCommand()`), a minimal meta is constructed
|
|
141
|
+
* from the command's own schema.
|
|
142
|
+
*
|
|
143
|
+
* @internal — populated by CLI dispatch, not for public use.
|
|
144
|
+
*/
|
|
145
|
+
readonly meta?: CommandMeta;
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* CLI plugins registered on the parent `CLIBuilder`.
|
|
149
|
+
*
|
|
150
|
+
* @internal — threaded through from CLI dispatch.
|
|
151
|
+
*/
|
|
152
|
+
readonly plugins?: readonly CLIPlugin[];
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/**
|
|
156
|
+
* Structured result from running a command.
|
|
157
|
+
*
|
|
158
|
+
* Contains the exit code, captured stdout/stderr output, and an `error`
|
|
159
|
+
* field that is `undefined` on success and populated on failure.
|
|
160
|
+
*/
|
|
161
|
+
interface RunResult {
|
|
162
|
+
/** Process exit code. 0 = success. */
|
|
163
|
+
readonly exitCode: number;
|
|
164
|
+
|
|
165
|
+
/** Captured stdout lines (from `out.log` and `out.info`). */
|
|
166
|
+
readonly stdout: readonly string[];
|
|
167
|
+
|
|
168
|
+
/** Captured stderr lines (from `out.warn` and `out.error`). */
|
|
169
|
+
readonly stderr: readonly string[];
|
|
170
|
+
|
|
171
|
+
/**
|
|
172
|
+
* Captured spinner and progress lifecycle events.
|
|
173
|
+
*
|
|
174
|
+
* Recorded separately from stdout/stderr — handlers that call
|
|
175
|
+
* `out.spinner()` or `out.progress()` produce events here, enabling
|
|
176
|
+
* targeted assertions on activity lifecycle without parsing text.
|
|
177
|
+
*/
|
|
178
|
+
readonly activity: readonly ActivityEvent[];
|
|
179
|
+
|
|
180
|
+
/**
|
|
181
|
+
* The error that caused a non-zero exit, or `undefined` on success.
|
|
182
|
+
* `CLIError` instances are preserved; unknown errors are wrapped.
|
|
183
|
+
*/
|
|
184
|
+
readonly error: CLIError | undefined;
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
export type { RunOptions, RunResult };
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# testkit — In-process test harness (public API)
|
|
2
|
+
|
|
3
|
+
Not just test utilities — first-class module exported from the package. Testkit symbols are
|
|
4
|
+
re-exported from the `dreamcli/testkit` subpath (curating barrel at `src/testkit.ts`). This internal
|
|
5
|
+
`core/testkit/` module is unchanged.
|
|
6
|
+
|
|
7
|
+
## CORE API
|
|
8
|
+
|
|
9
|
+
**`runCommand(cmd, argv, options?): Promise<RunResult>`**
|
|
10
|
+
|
|
11
|
+
Complete execution pipeline in-process: argv → parse → resolve → middleware chain → action handler →
|
|
12
|
+
captured output. Calls `out.stopActive()` in `finally` to clean up leaked spinner/progress timers.
|
|
13
|
+
|
|
14
|
+
**`RunResult`** (defined in `schema/run.ts`, re-exported here):
|
|
15
|
+
`{ exitCode, stdout: string[], stderr: string[], activity: ActivityEvent[], error? }`
|
|
16
|
+
|
|
17
|
+
**`RunOptions`** — the injectable testing seam:
|
|
18
|
+
|
|
19
|
+
| Option | Purpose |
|
|
20
|
+
| ----------- | ------------------------------------------------- |
|
|
21
|
+
| `env` | `Record<string, string>` — replaces `process.env` |
|
|
22
|
+
| `config` | JSON config object |
|
|
23
|
+
| `answers` | `Record<string, TestAnswer>` — prompt responses |
|
|
24
|
+
| `prompter` | Full `PromptEngine` override |
|
|
25
|
+
| `verbosity` | `'normal' \| 'quiet'` |
|
|
26
|
+
| `jsonMode` | boolean — enable JSON output |
|
|
27
|
+
| `isTTY` | boolean — simulate TTY |
|
|
28
|
+
| `help` | `HelpOptions` — help formatting (width, binName) |
|
|
29
|
+
|
|
30
|
+
## TEST FILES (7)
|
|
31
|
+
|
|
32
|
+
| File | Tests |
|
|
33
|
+
| -------------------------------- | --------------------------------------------- |
|
|
34
|
+
| `testkit.test.ts` | Core `runCommand()` behavior |
|
|
35
|
+
| `testkit-json.test.ts` | JSON mode output |
|
|
36
|
+
| `testkit-tty.test.ts` | TTY detection + behavior |
|
|
37
|
+
| `testkit-prompt.test.ts` | Prompt resolution via answers |
|
|
38
|
+
| `testkit-nesting.test.ts` | Nested command dispatch via testkit |
|
|
39
|
+
| `output-e2e.test.ts` | Full pipeline: output modes x verbosity x CLI |
|
|
40
|
+
| `middleware-context-e2e.test.ts` | Middleware composition + context typing |
|
|
41
|
+
|
|
42
|
+
## ASSERTIONS
|
|
43
|
+
|
|
44
|
+
- Output arrays include trailing `\n` — assert `['Hello\n']` not `['Hello']`
|
|
45
|
+
- JSON output: `JSON.parse(result.stdout[0] ?? '')` then `toEqual`
|
|
46
|
+
- Error checking: `result.error?.code` for structured errors
|
|
47
|
+
- Activity events: `result.activity` array of `ActivityEvent` discriminated unions
|
|
48
|
+
- Type testing: `expectTypeOf(ctx).toEqualTypeOf<Readonly<...>>()` in middleware E2E
|
|
49
|
+
|
|
50
|
+
## GOTCHAS
|
|
51
|
+
|
|
52
|
+
- `mergedSchema` field on `RunOptions` is `@internal` — used by CLI dispatch layer only
|
|
53
|
+
- `CaptureOutputChannel` (from output/) wired here for output + activity capture
|
|
54
|
+
- `formatRootHelp()` (in `cli/root-help.ts`) re-exported as `@internal` for CLI-level help rendering
|
|
55
|
+
- Direct imports: `schema/command.ts`, `schema/flag.ts`, `schema/arg.ts` (not through barrel)
|