@kjanat/dreamcli 1.0.0 → 2.0.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 +63 -6
- package/LICENSE +1 -1
- package/README.md +296 -164
- package/dist/core/cli/dispatch.d.mts +85 -0
- package/dist/core/cli/dispatch.mjs +1 -0
- package/dist/core/cli/index.d.mts +418 -0
- package/dist/core/cli/index.mjs +1 -0
- package/dist/core/cli/planner.d.mts +143 -0
- package/dist/core/cli/planner.mjs +1 -0
- package/dist/core/cli/plugin.d.mts +94 -0
- package/dist/core/cli/plugin.mjs +1 -0
- package/dist/core/cli/propagate.d.mts +39 -0
- package/dist/core/cli/propagate.mjs +1 -0
- package/dist/core/cli/root-help.d.mts +28 -0
- package/dist/core/cli/root-help.mjs +7 -0
- package/dist/core/cli/root-surface.d.mts +42 -0
- package/dist/core/cli/root-surface.mjs +1 -0
- package/dist/core/cli/runtime-preflight.d.mts +149 -0
- package/dist/core/cli/runtime-preflight.mjs +1 -0
- package/dist/core/completion/index.d.mts +46 -0
- package/dist/core/completion/index.mjs +1 -0
- package/dist/core/completion/shells/bash.d.mts +24 -0
- package/dist/core/completion/shells/bash.mjs +3 -0
- package/dist/core/completion/shells/fish.d.mts +20 -0
- package/dist/core/completion/shells/fish.mjs +2 -0
- package/dist/core/completion/shells/powershell.d.mts +14 -0
- package/dist/core/completion/shells/powershell.mjs +2 -0
- package/dist/core/completion/shells/shared.d.mts +139 -0
- package/dist/core/completion/shells/shared.mjs +1 -0
- package/dist/core/completion/shells/zsh.d.mts +24 -0
- package/dist/core/completion/shells/zsh.mjs +2 -0
- package/dist/core/config/index.d.mts +161 -0
- package/dist/core/config/index.mjs +1 -0
- package/dist/core/config/package-json.d.mts +68 -0
- package/dist/core/config/package-json.mjs +1 -0
- package/dist/core/errors/index.d.mts +126 -0
- package/dist/core/errors/index.mjs +1 -0
- package/dist/core/execution/index.d.mts +49 -0
- package/dist/core/execution/index.mjs +1 -0
- package/dist/core/help/index.d.mts +49 -0
- package/dist/core/help/index.mjs +8 -0
- package/dist/core/json-schema/index.d.mts +109 -0
- package/dist/core/json-schema/index.mjs +55 -0
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +185 -0
- package/dist/core/json-schema/meta-descriptions.generated.mjs +28 -0
- package/dist/core/output/activity.d.mts +194 -0
- package/dist/core/output/activity.mjs +1 -0
- package/dist/core/output/contracts.d.mts +88 -0
- package/dist/core/output/contracts.mjs +1 -0
- package/dist/core/output/display-value.d.mts +19 -0
- package/dist/core/output/display-value.mjs +1 -0
- package/dist/core/output/index.d.mts +280 -0
- package/dist/core/output/index.mjs +2 -0
- package/dist/core/output/renderers.d.mts +46 -0
- package/dist/core/output/renderers.mjs +1 -0
- package/dist/core/output/writer.d.mts +40 -0
- package/dist/core/output/writer.mjs +1 -0
- package/dist/core/parse/index.d.mts +79 -0
- package/dist/core/parse/index.mjs +1 -0
- package/dist/core/prompt/index.d.mts +205 -0
- package/dist/core/prompt/index.mjs +6 -0
- package/dist/core/resolve/args.d.mts +8 -0
- package/dist/core/resolve/args.mjs +1 -0
- package/dist/core/resolve/coerce.d.mts +22 -0
- package/dist/core/resolve/coerce.mjs +1 -0
- package/dist/core/resolve/config.d.mts +10 -0
- package/dist/core/resolve/config.mjs +1 -0
- package/dist/core/resolve/contracts.d.mts +112 -0
- package/dist/core/resolve/errors.d.mts +11 -0
- package/dist/core/resolve/errors.mjs +2 -0
- package/dist/core/resolve/flags.d.mts +10 -0
- package/dist/core/resolve/flags.mjs +1 -0
- package/dist/core/resolve/index.d.mts +42 -0
- package/dist/core/resolve/index.mjs +1 -0
- package/dist/core/resolve/property.d.mts +47 -0
- package/dist/core/resolve/property.mjs +1 -0
- package/dist/core/schema/activity.d.mts +169 -0
- package/dist/core/schema/arg.d.mts +559 -0
- package/dist/core/schema/arg.mjs +1 -0
- package/dist/core/schema/command.d.mts +960 -0
- package/dist/core/schema/command.mjs +1 -0
- package/dist/core/schema/flag.d.mts +491 -0
- package/dist/core/schema/flag.mjs +1 -0
- package/dist/core/schema/index.d.mts +8 -0
- package/dist/core/schema/middleware.d.mts +122 -0
- package/dist/core/schema/middleware.mjs +1 -0
- package/dist/core/schema/prompt.d.mts +117 -0
- package/dist/core/schema/run.d.mts +171 -0
- package/dist/core/schema-dsl/runtime.d.mts +144 -0
- package/dist/core/schema-dsl/runtime.mjs +2 -0
- package/dist/core/schema-dsl/to-json-schema.d.mts +30 -0
- package/dist/core/schema-dsl/to-json-schema.mjs +1 -0
- package/dist/core/testkit/index.d.mts +54 -0
- package/dist/core/testkit/index.mjs +1 -0
- package/dist/index.d.mts +28 -920
- package/dist/index.mjs +1 -10
- package/dist/runtime/adapter.d.mts +212 -0
- package/dist/{adapter-B37d9oia.mjs → runtime/adapter.mjs} +1 -1
- package/dist/runtime/auto.d.mts +26 -0
- package/dist/runtime/auto.mjs +1 -0
- package/dist/runtime/bun.d.mts +28 -0
- package/dist/runtime/bun.mjs +1 -0
- package/dist/runtime/deno.d.mts +76 -0
- package/dist/runtime/deno.mjs +2 -0
- package/dist/runtime/detect.d.mts +86 -0
- package/dist/runtime/detect.mjs +1 -0
- package/dist/runtime/index.d.mts +7 -0
- package/dist/runtime/node.d.mts +65 -0
- package/dist/runtime/node.mjs +2 -0
- package/dist/runtime/paths.d.mts +31 -0
- package/dist/runtime/paths.mjs +1 -0
- package/dist/runtime/support.d.mts +42 -0
- package/dist/runtime/support.mjs +1 -0
- package/dist/runtime.d.mts +6 -252
- package/dist/runtime.mjs +1 -1
- package/dist/testkit.d.mts +5 -24
- package/dist/testkit.mjs +1 -1
- package/dist/version.d.mts +16 -0
- package/dist/version.mjs +1 -0
- package/dreamcli.schema.json +338 -0
- package/examples/basic.ts +2 -2
- package/examples/gh/package.json +7 -11
- package/examples/gh/src/commands/auth.ts +2 -2
- package/examples/gh/src/commands/issue.ts +4 -4
- package/examples/gh/src/commands/pr.ts +4 -4
- package/examples/gh/src/docs.ts +11 -0
- package/examples/gh/src/lib/auth.ts +1 -1
- package/examples/gh/src/main.test.ts +6 -5
- package/examples/gh/src/main.ts +8 -6
- package/examples/interactive.ts +3 -3
- package/examples/json-mode.ts +4 -6
- package/examples/middleware.ts +3 -3
- package/examples/multi-command.ts +3 -3
- package/examples/spinner-progress.ts +5 -5
- package/examples/testing.ts +8 -6
- package/package.json +70 -44
- package/src/core/cli/dispatch.ts +4 -0
- package/src/core/cli/index.ts +185 -632
- package/src/core/cli/planner.ts +413 -0
- package/src/core/cli/plugin.ts +7 -1
- package/src/core/cli/propagate.ts +1 -1
- package/src/core/cli/runtime-preflight.ts +409 -0
- package/src/core/completion/index.ts +15 -9
- package/src/core/completion/shells/bash.ts +6 -3
- package/src/core/completion/shells/fish.ts +245 -10
- package/src/core/completion/shells/powershell.ts +390 -9
- package/src/core/completion/shells/shared.ts +4 -4
- package/src/core/completion/shells/zsh.ts +12 -7
- package/src/core/config/index.ts +7 -4
- package/src/core/config/package-json.ts +6 -2
- package/src/core/errors/index.ts +23 -8
- package/src/core/execution/index.ts +270 -0
- package/src/core/help/index.ts +13 -15
- package/src/core/json-schema/index.ts +193 -7
- package/src/core/json-schema/meta-descriptions.generated.ts +202 -0
- package/src/core/output/contracts.ts +194 -0
- package/src/core/output/index.ts +47 -82
- package/src/core/output/renderers.ts +125 -0
- package/src/core/parse/index.ts +39 -21
- package/src/core/prompt/index.ts +44 -27
- package/src/core/resolve/args.ts +144 -0
- package/src/core/resolve/coerce.ts +432 -0
- package/src/core/resolve/config.ts +26 -0
- package/src/core/resolve/contracts.ts +135 -0
- package/src/core/resolve/errors.ts +227 -0
- package/src/core/resolve/flags.ts +205 -0
- package/src/core/resolve/index.ts +41 -1264
- package/src/core/resolve/property.ts +99 -0
- package/src/core/schema/activity.ts +3 -0
- package/src/core/schema/arg.ts +26 -14
- package/src/core/schema/command.ts +265 -38
- package/src/core/schema/flag.ts +120 -15
- package/src/core/schema/index.ts +11 -2
- package/src/core/schema/middleware.ts +6 -6
- package/src/core/schema/prompt.ts +9 -1
- package/src/core/schema/run.ts +25 -17
- package/src/core/schema-dsl/index.ts +109 -0
- package/src/core/schema-dsl/parse.ts +262 -0
- package/src/core/schema-dsl/runtime.ts +609 -0
- package/src/core/schema-dsl/to-json-schema.ts +102 -0
- package/src/core/testkit/index.ts +55 -297
- package/src/index.ts +10 -4
- package/src/runtime/adapter.ts +13 -10
- package/src/runtime/auto.ts +3 -3
- package/src/runtime/bun.ts +4 -4
- package/src/runtime/deno.ts +43 -29
- package/src/runtime/detect.ts +4 -1
- package/src/runtime/index.ts +1 -1
- package/src/runtime/node.ts +43 -21
- package/src/runtime/paths.ts +9 -3
- package/src/runtime/support.ts +20 -4
- package/src/runtime.ts +1 -1
- package/src/testkit.ts +10 -8
- package/dist/adapter-CCSh5juX.cjs +0 -1
- package/dist/adapter-DIwO-q7K.d.mts +0 -3447
- package/dist/adapter-DQnxxLiE.d.cts +0 -3447
- package/dist/auto-5cjZaF9V.mjs +0 -3
- package/dist/auto-B0eSgoDw.cjs +0 -3
- package/dist/index.cjs +0 -10
- package/dist/index.d.cts +0 -920
- package/dist/runtime.cjs +0 -1
- package/dist/runtime.d.cts +0 -253
- package/dist/testkit-CEDYPvhF.mjs +0 -14
- package/dist/testkit-ClIKijxC.cjs +0 -14
- package/dist/testkit.cjs +0 -1
- package/dist/testkit.d.cts +0 -25
- package/examples/gh/tsconfig.json +0 -37
- package/examples/tsconfig.json +0 -17
- package/src/core/cli/AGENTS.md +0 -72
- package/src/core/completion/AGENTS.md +0 -72
- package/src/core/completion/completion-test-helpers.ts +0 -48
- package/src/core/output/AGENTS.md +0 -69
- package/src/core/resolve/AGENTS.md +0 -69
- package/src/core/schema/AGENTS.md +0 -61
- package/src/core/testkit/AGENTS.md +0 -55
- package/src/runtime/AGENTS.md +0 -74
- package/src/runtime/test-helpers.ts +0 -40
|
@@ -1,53 +1,25 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Test harness: command.run() with injected state, output capture.
|
|
3
3
|
*
|
|
4
|
-
* Provides
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
* exitCode and captured output.
|
|
4
|
+
* Provides {@linkcode runCommand()} — the in-process test harness wrapper over DreamCLI's
|
|
5
|
+
* shared executor.\
|
|
6
|
+
* It wires capture output and standalone command metadata,
|
|
7
|
+
* then returns a structured {@linkcode RunResult} with exitCode and captured output.
|
|
8
8
|
*
|
|
9
|
-
*
|
|
10
|
-
* testable without touching process state.
|
|
9
|
+
* This keeps command tests process-free without testkit owning the canonical pipeline:
|
|
11
10
|
*
|
|
11
|
+
* ```text
|
|
12
|
+
* parse -> resolve -> execute
|
|
13
|
+
* ```
|
|
12
14
|
* @module dreamcli/core/testkit
|
|
13
15
|
*/
|
|
14
16
|
|
|
15
|
-
import
|
|
16
|
-
BeforeParseParams,
|
|
17
|
-
CLIPlugin,
|
|
18
|
-
ResolvedCommandParams,
|
|
19
|
-
} from '#internals/core/cli/plugin.ts';
|
|
20
|
-
import { CLIError } from '#internals/core/errors/index.ts';
|
|
21
|
-
import { formatHelp } from '#internals/core/help/index.ts';
|
|
17
|
+
import { buildRunResult, executeCommand } from '#internals/core/execution/index.ts';
|
|
22
18
|
import type { CapturedOutput } from '#internals/core/output/index.ts';
|
|
23
19
|
import { createCaptureOutput } from '#internals/core/output/index.ts';
|
|
24
|
-
import {
|
|
25
|
-
import { createTestPrompter } from '#internals/core/prompt/index.ts';
|
|
26
|
-
import type { DeprecationWarning, ResolveOptions } from '#internals/core/resolve/index.ts';
|
|
27
|
-
import { resolve } from '#internals/core/resolve/index.ts';
|
|
28
|
-
import type { ArgBuilder, ArgConfig } from '#internals/core/schema/arg.ts';
|
|
29
|
-
import type { CommandBuilder, CommandMeta, Out } from '#internals/core/schema/command.ts';
|
|
30
|
-
import type { FlagBuilder, FlagConfig } from '#internals/core/schema/flag.ts';
|
|
20
|
+
import type { CommandMeta, Out, RunnableCommand } from '#internals/core/schema/command.ts';
|
|
31
21
|
import type { RunOptions, RunResult } from '#internals/core/schema/run.ts';
|
|
32
22
|
|
|
33
|
-
// --- Internal types
|
|
34
|
-
|
|
35
|
-
/**
|
|
36
|
-
* The runtime shape of action handler params — unbranded.
|
|
37
|
-
*
|
|
38
|
-
* This is what `ActionParams<F, A>` looks like after type erasure.
|
|
39
|
-
* Used at the phantom-type boundary in `invokeHandler`.
|
|
40
|
-
*
|
|
41
|
-
* @internal
|
|
42
|
-
*/
|
|
43
|
-
interface HandlerParams {
|
|
44
|
-
readonly flags: Readonly<Record<string, unknown>>;
|
|
45
|
-
readonly args: Readonly<Record<string, unknown>>;
|
|
46
|
-
readonly ctx: Readonly<Record<string, unknown>>;
|
|
47
|
-
readonly out: Out;
|
|
48
|
-
readonly meta: CommandMeta;
|
|
49
|
-
}
|
|
50
|
-
|
|
51
23
|
// RunOptions and RunResult are defined in schema/run.ts so the execution
|
|
52
24
|
// contract is shared by schema, CLI dispatch, and testkit. Re-exported here
|
|
53
25
|
// for public testkit continuity.
|
|
@@ -57,27 +29,25 @@ interface HandlerParams {
|
|
|
57
29
|
/**
|
|
58
30
|
* Run a command builder against the given argv with injected options.
|
|
59
31
|
*
|
|
60
|
-
* This is the
|
|
61
|
-
* 1.
|
|
62
|
-
* 2.
|
|
63
|
-
* 3.
|
|
64
|
-
* 4.
|
|
65
|
-
* 5. Run derive/middleware/action execution steps
|
|
66
|
-
* 6. Return structured result
|
|
32
|
+
* This is the testkit wrapper around the shared executor:
|
|
33
|
+
* 1. Create or reuse capture output
|
|
34
|
+
* 2. Build standalone schema/meta defaults when CLI dispatch did not
|
|
35
|
+
* 3. Delegate parse -> resolve -> execute to the shared executor
|
|
36
|
+
* 4. Return the structured result with captured buffers
|
|
67
37
|
*
|
|
68
|
-
*
|
|
69
|
-
* appropriate exit codes. The function never throws.
|
|
38
|
+
* Errors are normalized by the shared executor into structured {@linkcode RunResult}s
|
|
39
|
+
* with appropriate exit codes. The function never throws.
|
|
70
40
|
*
|
|
71
41
|
* @param cmd - The command builder (must have an action handler)
|
|
72
42
|
* @param argv - Raw argv strings (NOT including the command name itself)
|
|
73
43
|
* @param options - Injectable runtime state
|
|
74
44
|
* @returns Structured run result with exit code and captured output
|
|
75
45
|
*/
|
|
76
|
-
async function runCommand
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
46
|
+
async function runCommand(
|
|
47
|
+
cmd: RunnableCommand,
|
|
48
|
+
argv: readonly string[],
|
|
49
|
+
options?: RunOptions,
|
|
50
|
+
): Promise<RunResult> {
|
|
81
51
|
let out: Out;
|
|
82
52
|
let captured: CapturedOutput;
|
|
83
53
|
if (options?.out !== undefined) {
|
|
@@ -104,262 +74,50 @@ async function runCommand<
|
|
|
104
74
|
command: schema.name,
|
|
105
75
|
};
|
|
106
76
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
out
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
if (!cmd.handler) {
|
|
116
|
-
const err = new CLIError(`Command '${cmd.schema.name}' has no action handler`, {
|
|
117
|
-
code: 'NO_ACTION',
|
|
118
|
-
suggest: `Add an .action() handler to the '${cmd.schema.name}' command`,
|
|
119
|
-
});
|
|
120
|
-
out.error(err.message);
|
|
121
|
-
return buildResult(1, captured, err);
|
|
122
|
-
}
|
|
123
|
-
|
|
124
|
-
try {
|
|
125
|
-
await runBeforeParseHooks(options?.plugins, {
|
|
126
|
-
argv,
|
|
127
|
-
command: schema,
|
|
128
|
-
meta,
|
|
129
|
-
out,
|
|
130
|
-
});
|
|
77
|
+
const result = await executeCommand({
|
|
78
|
+
command: cmd,
|
|
79
|
+
argv,
|
|
80
|
+
out,
|
|
81
|
+
schema,
|
|
82
|
+
meta,
|
|
83
|
+
...(options !== undefined ? { options } : {}),
|
|
84
|
+
});
|
|
131
85
|
|
|
132
|
-
|
|
133
|
-
const parsed = parse(schema, argv);
|
|
134
|
-
|
|
135
|
-
// -- Resolve -------------------------------------------------------------
|
|
136
|
-
// Determine the prompt engine: explicit prompter takes precedence,
|
|
137
|
-
// then answers convenience shortcut, then nothing (prompts skipped).
|
|
138
|
-
const effectivePrompter =
|
|
139
|
-
options?.prompter ??
|
|
140
|
-
(options?.answers !== undefined ? createTestPrompter(options.answers) : undefined);
|
|
141
|
-
const resolveOptions: ResolveOptions = {
|
|
142
|
-
...(options?.stdinData !== undefined ? { stdinData: options.stdinData } : {}),
|
|
143
|
-
...(options?.env !== undefined ? { env: options.env } : {}),
|
|
144
|
-
...(options?.config !== undefined ? { config: options.config } : {}),
|
|
145
|
-
...(effectivePrompter !== undefined ? { prompter: effectivePrompter } : {}),
|
|
146
|
-
};
|
|
147
|
-
const resolved = await resolve(schema, parsed, resolveOptions);
|
|
148
|
-
const resolvedParams: ResolvedCommandParams = {
|
|
149
|
-
args: resolved.args,
|
|
150
|
-
flags: resolved.flags,
|
|
151
|
-
deprecations: resolved.deprecations,
|
|
152
|
-
command: schema,
|
|
153
|
-
meta,
|
|
154
|
-
out,
|
|
155
|
-
};
|
|
156
|
-
|
|
157
|
-
await runResolvedHooks(options?.plugins, 'afterResolve', resolvedParams);
|
|
158
|
-
|
|
159
|
-
// -- Deprecation warnings ------------------------------------------------
|
|
160
|
-
for (const d of resolved.deprecations) {
|
|
161
|
-
out.warn(formatDeprecation(d));
|
|
162
|
-
}
|
|
163
|
-
|
|
164
|
-
// -- Execute middleware chain + handler -----------------------------------
|
|
165
|
-
// The resolver guarantees that resolved.flags and resolved.args match
|
|
166
|
-
// the shape declared by the command's flag/arg builders. The phantom
|
|
167
|
-
// types on CommandBuilder<F, A> are erased at runtime — the handler
|
|
168
|
-
// is just a function accepting a plain object. `executeWithMiddleware`
|
|
169
|
-
// runs the middleware chain then invokes the handler at the end.
|
|
170
|
-
await runResolvedHooks(options?.plugins, 'beforeAction', resolvedParams);
|
|
171
|
-
await executeWithExecutionSteps(cmd, resolved.flags, resolved.args, out, meta);
|
|
172
|
-
await runResolvedHooks(options?.plugins, 'afterAction', resolvedParams);
|
|
173
|
-
|
|
174
|
-
return buildResult(0, captured, undefined);
|
|
175
|
-
} catch (err: unknown) {
|
|
176
|
-
if (err instanceof CLIError) {
|
|
177
|
-
if (options?.jsonMode === true) {
|
|
178
|
-
out.json({ error: err.toJSON() });
|
|
179
|
-
} else {
|
|
180
|
-
out.error(err.message);
|
|
181
|
-
if (err.suggest !== undefined) {
|
|
182
|
-
out.error(`Suggestion: ${err.suggest}`);
|
|
183
|
-
}
|
|
184
|
-
}
|
|
185
|
-
return buildResult(err.exitCode, captured, err);
|
|
186
|
-
}
|
|
187
|
-
|
|
188
|
-
// Unknown error — wrap and exit 1
|
|
189
|
-
const message = err instanceof Error ? err.message : String(err);
|
|
190
|
-
const wrapped = new CLIError(`Unexpected error: ${message}`, {
|
|
191
|
-
code: 'UNEXPECTED_ERROR',
|
|
192
|
-
cause: err,
|
|
193
|
-
});
|
|
194
|
-
if (options?.jsonMode === true) {
|
|
195
|
-
out.json({ error: wrapped.toJSON() });
|
|
196
|
-
} else {
|
|
197
|
-
out.error(wrapped.message);
|
|
198
|
-
}
|
|
199
|
-
return buildResult(1, captured, wrapped);
|
|
200
|
-
} finally {
|
|
201
|
-
// Clean up any active spinner/progress timer that the handler
|
|
202
|
-
// failed to stop (e.g. unhandled exception before terminal method).
|
|
203
|
-
out.stopActive();
|
|
204
|
-
}
|
|
86
|
+
return buildRunResult(result, captured);
|
|
205
87
|
}
|
|
206
88
|
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
/**
|
|
210
|
-
* @internal
|
|
211
|
-
*/
|
|
212
|
-
async function runBeforeParseHooks(
|
|
213
|
-
plugins: readonly CLIPlugin[] | undefined,
|
|
214
|
-
params: BeforeParseParams,
|
|
215
|
-
): Promise<void> {
|
|
216
|
-
if (plugins === undefined) return;
|
|
217
|
-
for (const current of plugins) {
|
|
218
|
-
const hook = current.hooks.beforeParse;
|
|
219
|
-
if (hook !== undefined) await hook(params);
|
|
220
|
-
}
|
|
221
|
-
}
|
|
222
|
-
|
|
223
|
-
/**
|
|
224
|
-
* @internal
|
|
225
|
-
*/
|
|
226
|
-
async function runResolvedHooks(
|
|
227
|
-
plugins: readonly CLIPlugin[] | undefined,
|
|
228
|
-
hookName: ResolvedHookName,
|
|
229
|
-
params: ResolvedCommandParams,
|
|
230
|
-
): Promise<void> {
|
|
231
|
-
if (plugins === undefined) return;
|
|
232
|
-
for (const current of plugins) {
|
|
233
|
-
const hook = current.hooks[hookName];
|
|
234
|
-
if (hook !== undefined) await hook(params);
|
|
235
|
-
}
|
|
236
|
-
}
|
|
237
|
-
|
|
238
|
-
// --- Helpers
|
|
89
|
+
// --- Exports
|
|
239
90
|
|
|
240
91
|
/**
|
|
241
|
-
*
|
|
242
|
-
*
|
|
243
|
-
* Builds a continuation chain from the registered execution steps, preserving
|
|
244
|
-
* registration order across `derive()` and `middleware()`.
|
|
245
|
-
*
|
|
246
|
-
* - Derive steps run once, may validate/throw, and optionally return context
|
|
247
|
-
* additions merged into `ctx`.
|
|
248
|
-
* - Middleware steps can wrap downstream execution via `next(additions)`.
|
|
249
|
-
* - The terminal step invokes the action handler with the final accumulated ctx.
|
|
92
|
+
* Options for {@linkcode runCommand} — process-free command execution.
|
|
250
93
|
*
|
|
251
|
-
*
|
|
252
|
-
*
|
|
253
|
-
* the phantom types guarantee the handler expects that schema.
|
|
94
|
+
* Every field is optional. Inject env, config, prompt answers, and
|
|
95
|
+
* output capture without touching process state.
|
|
254
96
|
*
|
|
255
|
-
* @
|
|
97
|
+
* @example
|
|
98
|
+
* ```ts
|
|
99
|
+
* const result = await runCommand(cmd, ['--verbose'], {
|
|
100
|
+
* env: { LOG_LEVEL: 'debug' },
|
|
101
|
+
* config: { theme: 'dark' },
|
|
102
|
+
* });
|
|
103
|
+
* ```
|
|
256
104
|
*/
|
|
257
|
-
async function executeWithExecutionSteps<
|
|
258
|
-
F extends Record<string, FlagBuilder<FlagConfig>>,
|
|
259
|
-
A extends Record<string, ArgBuilder<ArgConfig>>,
|
|
260
|
-
C extends Record<string, unknown>,
|
|
261
|
-
>(
|
|
262
|
-
cmd: CommandBuilder<F, A, C>,
|
|
263
|
-
flags: Readonly<Record<string, unknown>>,
|
|
264
|
-
args: Readonly<Record<string, unknown>>,
|
|
265
|
-
out: Out,
|
|
266
|
-
meta: CommandMeta,
|
|
267
|
-
): Promise<void> {
|
|
268
|
-
const steps = cmd._executionSteps;
|
|
269
|
-
const handler = cmd.handler;
|
|
270
|
-
if (handler === undefined) {
|
|
271
|
-
throw new CLIError(`Command '${cmd.schema.name}' has no action handler`, {
|
|
272
|
-
code: 'NO_ACTION',
|
|
273
|
-
suggest: `Add an .action() handler to the '${cmd.schema.name}' command`,
|
|
274
|
-
});
|
|
275
|
-
}
|
|
276
|
-
|
|
277
|
-
// Terminal action — receives the final accumulated context.
|
|
278
|
-
type ChainFn = (ctx: Readonly<Record<string, unknown>>) => Promise<void>;
|
|
279
|
-
|
|
280
|
-
let chain: ChainFn = async (ctx) => {
|
|
281
|
-
const params: HandlerParams = { flags, args, ctx, out, meta };
|
|
282
|
-
// Phantom-type erasure: handler is (params: object) => void | Promise<void> at runtime.
|
|
283
|
-
await (handler as (p: HandlerParams) => void | Promise<void>)(params);
|
|
284
|
-
};
|
|
285
|
-
|
|
286
|
-
// Wrap from back to front so registration order is preserved.
|
|
287
|
-
for (let i = steps.length - 1; i >= 0; i--) {
|
|
288
|
-
const step = steps[i];
|
|
289
|
-
if (step === undefined) continue; // satisfy noUncheckedIndexedAccess
|
|
290
|
-
const downstream = chain; // capture for closure
|
|
291
|
-
switch (step.kind) {
|
|
292
|
-
case 'derive':
|
|
293
|
-
chain = async (ctx) => {
|
|
294
|
-
const additions = await step.handler({ args, flags, ctx, out, meta });
|
|
295
|
-
if (additions === undefined) {
|
|
296
|
-
await downstream(ctx);
|
|
297
|
-
return;
|
|
298
|
-
}
|
|
299
|
-
if (typeof additions !== 'object' || additions === null || Array.isArray(additions)) {
|
|
300
|
-
throw new CLIError('derive() must return an object or undefined', {
|
|
301
|
-
code: 'INVALID_BUILDER_STATE',
|
|
302
|
-
suggest:
|
|
303
|
-
'Return an object to add context, or return nothing for validation-only derive handlers',
|
|
304
|
-
});
|
|
305
|
-
}
|
|
306
|
-
await downstream({ ...ctx, ...additions });
|
|
307
|
-
};
|
|
308
|
-
break;
|
|
309
|
-
case 'middleware':
|
|
310
|
-
chain = async (ctx) => {
|
|
311
|
-
await step.handler({
|
|
312
|
-
args,
|
|
313
|
-
flags,
|
|
314
|
-
ctx,
|
|
315
|
-
out,
|
|
316
|
-
meta,
|
|
317
|
-
next: async (additions) => {
|
|
318
|
-
await downstream({ ...ctx, ...additions });
|
|
319
|
-
},
|
|
320
|
-
});
|
|
321
|
-
};
|
|
322
|
-
break;
|
|
323
|
-
}
|
|
324
|
-
}
|
|
325
|
-
|
|
326
|
-
// Start with empty context — middleware builds it up.
|
|
327
|
-
await chain({});
|
|
328
|
-
}
|
|
329
|
-
|
|
330
|
-
/** Build a `RunResult` from parts. */
|
|
331
|
-
function buildResult(
|
|
332
|
-
exitCode: number,
|
|
333
|
-
captured: CapturedOutput,
|
|
334
|
-
error: CLIError | undefined,
|
|
335
|
-
): RunResult {
|
|
336
|
-
return {
|
|
337
|
-
exitCode,
|
|
338
|
-
stdout: captured.stdout,
|
|
339
|
-
stderr: captured.stderr,
|
|
340
|
-
activity: captured.activity,
|
|
341
|
-
error,
|
|
342
|
-
};
|
|
343
|
-
}
|
|
344
|
-
|
|
345
|
-
// --- Deprecation formatting (presentation layer — not resolve's responsibility)
|
|
346
|
-
|
|
347
105
|
/**
|
|
348
|
-
*
|
|
106
|
+
* Structured result from {@linkcode runCommand}.
|
|
349
107
|
*
|
|
350
|
-
*
|
|
351
|
-
*
|
|
108
|
+
* Contains the exit code, captured stdout/stderr output, recorded
|
|
109
|
+
* {@linkcode ActivityEvent | activity events}, and an `error` field
|
|
110
|
+
* that is `undefined` on success and a {@linkcode CLIError} on failure.
|
|
352
111
|
*
|
|
353
|
-
* @
|
|
112
|
+
* @example
|
|
113
|
+
* ```ts
|
|
114
|
+
* const result = await runCommand(greetCmd, ['World']);
|
|
115
|
+
*
|
|
116
|
+
* expect(result.exitCode).toBe(0);
|
|
117
|
+
* expect(result.stdout).toContain('Hello, World!');
|
|
118
|
+
* expect(result.error).toBeUndefined();
|
|
119
|
+
* ```
|
|
354
120
|
*/
|
|
355
|
-
function formatDeprecation(d: DeprecationWarning): string {
|
|
356
|
-
const entity = d.kind === 'flag' ? `flag --${d.name}` : `argument <${d.name}>`;
|
|
357
|
-
return typeof d.message === 'string'
|
|
358
|
-
? `Warning: ${entity} is deprecated: ${d.message}`
|
|
359
|
-
: `Warning: ${entity} is deprecated`;
|
|
360
|
-
}
|
|
361
|
-
|
|
362
|
-
// --- Exports
|
|
363
|
-
|
|
364
121
|
export type { RunOptions, RunResult };
|
|
122
|
+
|
|
365
123
|
export { runCommand };
|
package/src/index.ts
CHANGED
|
@@ -12,10 +12,10 @@
|
|
|
12
12
|
* not the typical starting point for application code.
|
|
13
13
|
*
|
|
14
14
|
* Test utilities (runCommand, createCaptureOutput, createTestPrompter, etc.)
|
|
15
|
-
* are available from
|
|
16
|
-
* RuntimeAdapter, etc.) are available from
|
|
15
|
+
* are available from `@kjanat/dreamcli/testkit`. Runtime adapters (createAdapter,
|
|
16
|
+
* RuntimeAdapter, etc.) are available from `@kjanat/dreamcli/runtime`.
|
|
17
17
|
*
|
|
18
|
-
* @module dreamcli
|
|
18
|
+
* @module @kjanat/dreamcli
|
|
19
19
|
*/
|
|
20
20
|
|
|
21
21
|
export type {
|
|
@@ -35,6 +35,8 @@ export type { CompletionOptions, Shell } from './core/completion/index.ts';
|
|
|
35
35
|
export {
|
|
36
36
|
generateBashCompletion,
|
|
37
37
|
generateCompletion,
|
|
38
|
+
generateFishCompletion,
|
|
39
|
+
generatePowerShellCompletion,
|
|
38
40
|
generateZshCompletion,
|
|
39
41
|
SHELLS,
|
|
40
42
|
} from './core/completion/index.ts';
|
|
@@ -75,7 +77,11 @@ export {
|
|
|
75
77
|
export type { HelpOptions } from './core/help/index.ts';
|
|
76
78
|
export { formatHelp } from './core/help/index.ts';
|
|
77
79
|
export type { JsonSchemaOptions } from './core/json-schema/index.ts';
|
|
78
|
-
export {
|
|
80
|
+
export {
|
|
81
|
+
definitionMetaSchema,
|
|
82
|
+
generateInputSchema,
|
|
83
|
+
generateSchema,
|
|
84
|
+
} from './core/json-schema/index.ts';
|
|
79
85
|
export type { OutputOptions, Verbosity, WriteFn } from './core/output/index.ts';
|
|
80
86
|
export { createOutput } from './core/output/index.ts';
|
|
81
87
|
export type { ParseResult, Token } from './core/parse/index.ts';
|
package/src/runtime/adapter.ts
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
* argv/env access, I/O streams, TTY detection, working directory, and
|
|
7
7
|
* process exit. Concrete implementations exist for Node, Bun, and Deno.
|
|
8
8
|
*
|
|
9
|
-
* @module dreamcli/runtime/adapter
|
|
9
|
+
* @module @kjanat/dreamcli/runtime/adapter
|
|
10
10
|
*/
|
|
11
11
|
|
|
12
12
|
import type { WriteFn } from '#internals/core/output/index.ts';
|
|
@@ -25,7 +25,7 @@ import type { ReadFn } from '#internals/core/prompt/index.ts';
|
|
|
25
25
|
* Adapters are designed to be:
|
|
26
26
|
* - **Immutable in shape:** all properties are readonly
|
|
27
27
|
* - **Minimal:** only the operations the framework actually needs
|
|
28
|
-
* - **Testable:** easily stubbed in tests via
|
|
28
|
+
* - **Testable:** easily stubbed in tests via {@linkcode createTestAdapter | createTestAdapter()}
|
|
29
29
|
*
|
|
30
30
|
* @example
|
|
31
31
|
* ```ts
|
|
@@ -150,7 +150,7 @@ interface TestAdapterOptions {
|
|
|
150
150
|
/**
|
|
151
151
|
* Stdin line reader (defaults to returning `null` — immediate EOF).
|
|
152
152
|
*
|
|
153
|
-
* Use a custom
|
|
153
|
+
* Use a custom {@linkcode ReadFn} to simulate user input in tests.
|
|
154
154
|
*/
|
|
155
155
|
readonly stdin?: ReadFn;
|
|
156
156
|
|
|
@@ -177,7 +177,7 @@ interface TestAdapterOptions {
|
|
|
177
177
|
readonly stdinIsTTY?: boolean;
|
|
178
178
|
|
|
179
179
|
/**
|
|
180
|
-
* Exit function (defaults to throwing
|
|
180
|
+
* Exit function (defaults to throwing {@linkcode ExitError}).
|
|
181
181
|
* The default throw-based exit allows tests to catch the exit code.
|
|
182
182
|
*/
|
|
183
183
|
readonly exit?: (code: number) => never;
|
|
@@ -208,10 +208,12 @@ interface TestAdapterOptions {
|
|
|
208
208
|
}
|
|
209
209
|
|
|
210
210
|
/**
|
|
211
|
-
* Error thrown by
|
|
211
|
+
* Error thrown by adapter implementations that model process exit as an
|
|
212
|
+
* exception instead of terminating immediately.
|
|
212
213
|
*
|
|
213
|
-
*
|
|
214
|
-
*
|
|
214
|
+
* Runtime and CLI dispatch layers can catch this to perform real process
|
|
215
|
+
* termination, while tests can assert on exit codes without killing the
|
|
216
|
+
* runner:
|
|
215
217
|
*
|
|
216
218
|
* ```ts
|
|
217
219
|
* try {
|
|
@@ -222,12 +224,13 @@ interface TestAdapterOptions {
|
|
|
222
224
|
* ```
|
|
223
225
|
*/
|
|
224
226
|
class ExitError extends Error {
|
|
225
|
-
/**
|
|
227
|
+
/** Error name — always `'ExitError'` for `instanceof` checks. */
|
|
226
228
|
override readonly name = 'ExitError';
|
|
227
229
|
|
|
228
230
|
/** The exit code passed to `exit()`. */
|
|
229
231
|
readonly code: number;
|
|
230
232
|
|
|
233
|
+
/** Create an ExitError for the given process exit code. */
|
|
231
234
|
constructor(code: number) {
|
|
232
235
|
super(`Process exited with code ${code}`);
|
|
233
236
|
this.code = code;
|
|
@@ -246,12 +249,12 @@ const noopReadFile: (path: string) => Promise<string | null> = () => Promise.res
|
|
|
246
249
|
/**
|
|
247
250
|
* Create a test runtime adapter with injectable process state.
|
|
248
251
|
*
|
|
249
|
-
* Use this in
|
|
252
|
+
* Use this in `@kjanat/dreamcli/testkit` tests when you need to simulate argv,
|
|
250
253
|
* environment variables, TTY state, stdin, or config-file reads without
|
|
251
254
|
* touching the host process.
|
|
252
255
|
*
|
|
253
256
|
* @param options - Optional overrides for any adapter field.
|
|
254
|
-
* @returns A
|
|
257
|
+
* @returns A {@linkcode RuntimeAdapter} suitable for test scenarios.
|
|
255
258
|
*
|
|
256
259
|
* @example
|
|
257
260
|
* ```ts
|
package/src/runtime/auto.ts
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
* Node adapter for unknown runtimes (safest default — most runtimes
|
|
7
7
|
* provide a Node-compatible `process` global).
|
|
8
8
|
*
|
|
9
|
-
* @module dreamcli/runtime/auto
|
|
9
|
+
* @module @kjanat/dreamcli/runtime/auto
|
|
10
10
|
*/
|
|
11
11
|
|
|
12
12
|
import type { RuntimeAdapter } from './adapter.ts';
|
|
@@ -73,11 +73,11 @@ function getInjectedDenoNamespace(globals: GlobalForDetect): DenoNamespace | und
|
|
|
73
73
|
*
|
|
74
74
|
* @param globals - Override `globalThis` for testing. Production callers
|
|
75
75
|
* should omit this parameter.
|
|
76
|
-
* @returns A
|
|
76
|
+
* @returns A {@linkcode RuntimeAdapter} for the detected runtime.
|
|
77
77
|
*
|
|
78
78
|
* @example
|
|
79
79
|
* ```ts
|
|
80
|
-
* import { cli } from 'dreamcli';
|
|
80
|
+
* import { cli } from '@kjanat/dreamcli';
|
|
81
81
|
*
|
|
82
82
|
* // Auto-detects Node/Bun/Deno and creates the right adapter
|
|
83
83
|
* cli('mycli').run(); // uses createAdapter() internally
|
package/src/runtime/bun.ts
CHANGED
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
* 2. Provide an extension point for Bun-specific overrides in the future
|
|
10
10
|
* (e.g. `Bun.write` for optimized I/O, `Bun.stdin` for streaming)
|
|
11
11
|
*
|
|
12
|
-
* @module dreamcli/runtime/bun
|
|
12
|
+
* @module @kjanat/dreamcli/runtime/bun
|
|
13
13
|
*/
|
|
14
14
|
|
|
15
15
|
import type { RuntimeAdapter } from './adapter.ts';
|
|
@@ -33,12 +33,12 @@ function resolveBunVersion(proc?: NodeProcess): string | undefined {
|
|
|
33
33
|
* here without changing the public API.
|
|
34
34
|
*
|
|
35
35
|
* @param proc - Override the process object (useful for testing the adapter itself).
|
|
36
|
-
* @returns A
|
|
36
|
+
* @returns A {@linkcode RuntimeAdapter} backed by Bun's process state.
|
|
37
37
|
*
|
|
38
38
|
* @example
|
|
39
39
|
* ```ts
|
|
40
|
-
* import { cli } from 'dreamcli';
|
|
41
|
-
* import { createBunAdapter } from 'dreamcli/runtime
|
|
40
|
+
* import { cli } from '@kjanat/dreamcli';
|
|
41
|
+
* import { createBunAdapter } from '@kjanat/dreamcli/runtime';
|
|
42
42
|
*
|
|
43
43
|
* cli('mycli')
|
|
44
44
|
* .command(deploy)
|