@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,365 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Test harness: command.run() with injected state, output capture.
|
|
3
|
+
*
|
|
4
|
+
* Provides `runCommand()` — the core execution pipeline that parses argv,
|
|
5
|
+
* resolves values (CLI → env → config → default), creates an output channel,
|
|
6
|
+
* and invokes the action handler. Returns a structured `RunResult` with
|
|
7
|
+
* exitCode and captured output.
|
|
8
|
+
*
|
|
9
|
+
* `CommandBuilder.run()` delegates to `runCommand()`, making commands
|
|
10
|
+
* testable without touching process state.
|
|
11
|
+
*
|
|
12
|
+
* @module dreamcli/core/testkit
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
import type {
|
|
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';
|
|
22
|
+
import type { CapturedOutput } from '#internals/core/output/index.ts';
|
|
23
|
+
import { createCaptureOutput } from '#internals/core/output/index.ts';
|
|
24
|
+
import { parse } from '#internals/core/parse/index.ts';
|
|
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';
|
|
31
|
+
import type { RunOptions, RunResult } from '#internals/core/schema/run.ts';
|
|
32
|
+
|
|
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
|
+
// RunOptions and RunResult are defined in schema/run.ts so the execution
|
|
52
|
+
// contract is shared by schema, CLI dispatch, and testkit. Re-exported here
|
|
53
|
+
// for public testkit continuity.
|
|
54
|
+
|
|
55
|
+
// --- Core execution pipeline
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* Run a command builder against the given argv with injected options.
|
|
59
|
+
*
|
|
60
|
+
* This is the core execution pipeline:
|
|
61
|
+
* 1. Detect `--help` / `-h` → print help text, exit 0
|
|
62
|
+
* 2. Parse argv against the command schema
|
|
63
|
+
* 3. Resolve values (CLI → env → config → default)
|
|
64
|
+
* 4. Create a capture output channel
|
|
65
|
+
* 5. Run derive/middleware/action execution steps
|
|
66
|
+
* 6. Return structured result
|
|
67
|
+
*
|
|
68
|
+
* All errors are caught and converted to structured `RunResult`s with
|
|
69
|
+
* appropriate exit codes. The function never throws.
|
|
70
|
+
*
|
|
71
|
+
* @param cmd - The command builder (must have an action handler)
|
|
72
|
+
* @param argv - Raw argv strings (NOT including the command name itself)
|
|
73
|
+
* @param options - Injectable runtime state
|
|
74
|
+
* @returns Structured run result with exit code and captured output
|
|
75
|
+
*/
|
|
76
|
+
async function runCommand<
|
|
77
|
+
F extends Record<string, FlagBuilder<FlagConfig>>,
|
|
78
|
+
A extends Record<string, ArgBuilder<ArgConfig>>,
|
|
79
|
+
C extends Record<string, unknown> = Record<string, never>,
|
|
80
|
+
>(cmd: CommandBuilder<F, A, C>, argv: readonly string[], options?: RunOptions): Promise<RunResult> {
|
|
81
|
+
let out: Out;
|
|
82
|
+
let captured: CapturedOutput;
|
|
83
|
+
if (options?.out !== undefined) {
|
|
84
|
+
out = options.out;
|
|
85
|
+
captured = options.captured ?? { stdout: [], stderr: [], activity: [] };
|
|
86
|
+
} else {
|
|
87
|
+
const captureOptions = {
|
|
88
|
+
...(options?.verbosity !== undefined ? { verbosity: options.verbosity } : {}),
|
|
89
|
+
...(options?.jsonMode !== undefined ? { jsonMode: options.jsonMode } : {}),
|
|
90
|
+
...(options?.isTTY !== undefined ? { isTTY: options.isTTY } : {}),
|
|
91
|
+
};
|
|
92
|
+
[out, captured] = createCaptureOutput(
|
|
93
|
+
Object.keys(captureOptions).length > 0 ? captureOptions : undefined,
|
|
94
|
+
);
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
// Use merged schema (with propagated flags) when provided by dispatch layer,
|
|
98
|
+
// otherwise fall back to the command's own schema.
|
|
99
|
+
const schema = options?.mergedSchema ?? cmd.schema;
|
|
100
|
+
const meta: CommandMeta = options?.meta ?? {
|
|
101
|
+
name: schema.name,
|
|
102
|
+
bin: options?.help?.binName ?? schema.name,
|
|
103
|
+
version: undefined,
|
|
104
|
+
command: schema.name,
|
|
105
|
+
};
|
|
106
|
+
|
|
107
|
+
// -- Help detection -------------------------------------------------------
|
|
108
|
+
if (argv.includes('--help') || argv.includes('-h')) {
|
|
109
|
+
const helpText = formatHelp(schema, options?.help);
|
|
110
|
+
out.log(helpText);
|
|
111
|
+
return buildResult(0, captured, undefined);
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
// -- No action handler → error -------------------------------------------
|
|
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
|
+
});
|
|
131
|
+
|
|
132
|
+
// -- Parse ---------------------------------------------------------------
|
|
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
|
+
}
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
type ResolvedHookName = Exclude<keyof CLIPlugin['hooks'], 'beforeParse'>;
|
|
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
|
|
239
|
+
|
|
240
|
+
/**
|
|
241
|
+
* Execute the derive/middleware chain followed by the action handler.
|
|
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.
|
|
250
|
+
*
|
|
251
|
+
* This is the sole point where we bridge the phantom-type gap. The
|
|
252
|
+
* parse→resolve pipeline guarantees the runtime values match the schema;
|
|
253
|
+
* the phantom types guarantee the handler expects that schema.
|
|
254
|
+
*
|
|
255
|
+
* @internal
|
|
256
|
+
*/
|
|
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
|
+
/**
|
|
348
|
+
* Format a structured deprecation warning for human-readable stderr output.
|
|
349
|
+
*
|
|
350
|
+
* This is a **consumer-side** formatting function — the resolve layer returns
|
|
351
|
+
* structured `DeprecationWarning` data; consumers decide how to render it.
|
|
352
|
+
*
|
|
353
|
+
* @internal
|
|
354
|
+
*/
|
|
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
|
+
export type { RunOptions, RunResult };
|
|
365
|
+
export { runCommand };
|
package/src/index.ts
ADDED
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* DreamCLI — Schema-first, fully typed TypeScript CLI framework.
|
|
3
|
+
*
|
|
4
|
+
* Start here for most applications:
|
|
5
|
+
* - {@link cli} to define a program
|
|
6
|
+
* - {@link command} to define commands and groups
|
|
7
|
+
* - {@link flag} and {@link arg} to describe inputs
|
|
8
|
+
*
|
|
9
|
+
* This root entrypoint also re-exports lower-level building blocks such as
|
|
10
|
+
* parsing, resolution, config discovery, and help formatting. Those are useful
|
|
11
|
+
* for advanced integrations, custom tooling, or focused tests, but they are
|
|
12
|
+
* not the typical starting point for application code.
|
|
13
|
+
*
|
|
14
|
+
* Test utilities (runCommand, createCaptureOutput, createTestPrompter, etc.)
|
|
15
|
+
* are available from `dreamcli/testkit`. Runtime adapters (createAdapter,
|
|
16
|
+
* RuntimeAdapter, etc.) are available from `dreamcli/runtime`.
|
|
17
|
+
*
|
|
18
|
+
* @module dreamcli
|
|
19
|
+
*/
|
|
20
|
+
|
|
21
|
+
export type {
|
|
22
|
+
BeforeParseParams,
|
|
23
|
+
CLIOptions,
|
|
24
|
+
CLIPlugin,
|
|
25
|
+
CLIPluginHooks,
|
|
26
|
+
CLIRunOptions,
|
|
27
|
+
CLISchema,
|
|
28
|
+
ConfigSettings,
|
|
29
|
+
PackageJsonSettings,
|
|
30
|
+
PluginCommandContext,
|
|
31
|
+
ResolvedCommandParams,
|
|
32
|
+
} from './core/cli/index.ts';
|
|
33
|
+
export { CLIBuilder, cli, plugin } from './core/cli/index.ts';
|
|
34
|
+
export type { CompletionOptions, Shell } from './core/completion/index.ts';
|
|
35
|
+
export {
|
|
36
|
+
generateBashCompletion,
|
|
37
|
+
generateCompletion,
|
|
38
|
+
generateZshCompletion,
|
|
39
|
+
SHELLS,
|
|
40
|
+
} from './core/completion/index.ts';
|
|
41
|
+
export type {
|
|
42
|
+
ConfigAdapter,
|
|
43
|
+
ConfigDiscoveryOptions,
|
|
44
|
+
ConfigDiscoveryResult,
|
|
45
|
+
ConfigFound,
|
|
46
|
+
ConfigNotFound,
|
|
47
|
+
FormatLoader,
|
|
48
|
+
PackageJsonAdapter,
|
|
49
|
+
PackageJsonData,
|
|
50
|
+
} from './core/config/index.ts';
|
|
51
|
+
export {
|
|
52
|
+
buildConfigSearchPaths,
|
|
53
|
+
configFormat,
|
|
54
|
+
discoverConfig,
|
|
55
|
+
discoverPackageJson,
|
|
56
|
+
inferCliName,
|
|
57
|
+
} from './core/config/index.ts';
|
|
58
|
+
export type {
|
|
59
|
+
CLIErrorJSON,
|
|
60
|
+
CLIErrorOptions,
|
|
61
|
+
ErrorCode,
|
|
62
|
+
ParseErrorCode,
|
|
63
|
+
ParseErrorOptions,
|
|
64
|
+
ValidationErrorCode,
|
|
65
|
+
ValidationErrorOptions,
|
|
66
|
+
} from './core/errors/index.ts';
|
|
67
|
+
export {
|
|
68
|
+
CLIError,
|
|
69
|
+
isCLIError,
|
|
70
|
+
isParseError,
|
|
71
|
+
isValidationError,
|
|
72
|
+
ParseError,
|
|
73
|
+
ValidationError,
|
|
74
|
+
} from './core/errors/index.ts';
|
|
75
|
+
export type { HelpOptions } from './core/help/index.ts';
|
|
76
|
+
export { formatHelp } from './core/help/index.ts';
|
|
77
|
+
export type { JsonSchemaOptions } from './core/json-schema/index.ts';
|
|
78
|
+
export { generateInputSchema, generateSchema } from './core/json-schema/index.ts';
|
|
79
|
+
export type { OutputOptions, Verbosity, WriteFn } from './core/output/index.ts';
|
|
80
|
+
export { createOutput } from './core/output/index.ts';
|
|
81
|
+
export type { ParseResult, Token } from './core/parse/index.ts';
|
|
82
|
+
export { parse, tokenize } from './core/parse/index.ts';
|
|
83
|
+
export type {
|
|
84
|
+
PromptEngine,
|
|
85
|
+
ReadFn,
|
|
86
|
+
ResolvedMultiselectPromptConfig,
|
|
87
|
+
ResolvedPromptConfig,
|
|
88
|
+
ResolvedSelectPromptConfig,
|
|
89
|
+
} from './core/prompt/index.ts';
|
|
90
|
+
export { createTerminalPrompter, resolvePromptConfig } from './core/prompt/index.ts';
|
|
91
|
+
export type { DeprecationWarning, ResolveOptions, ResolveResult } from './core/resolve/index.ts';
|
|
92
|
+
export { resolve } from './core/resolve/index.ts';
|
|
93
|
+
export type {
|
|
94
|
+
ActionHandler,
|
|
95
|
+
ActionParams,
|
|
96
|
+
ActivityEvent,
|
|
97
|
+
AnyCommandBuilder,
|
|
98
|
+
ArgConfig,
|
|
99
|
+
ArgFactory,
|
|
100
|
+
ArgKind,
|
|
101
|
+
ArgParseFn,
|
|
102
|
+
ArgPresence,
|
|
103
|
+
ArgSchema,
|
|
104
|
+
CommandArgEntry,
|
|
105
|
+
CommandConfig,
|
|
106
|
+
CommandExample,
|
|
107
|
+
CommandMeta,
|
|
108
|
+
CommandSchema,
|
|
109
|
+
ConfirmPromptConfig,
|
|
110
|
+
DeriveHandler,
|
|
111
|
+
DeriveParams,
|
|
112
|
+
Fallback,
|
|
113
|
+
FlagConfig,
|
|
114
|
+
FlagFactory,
|
|
115
|
+
FlagKind,
|
|
116
|
+
FlagParseFn,
|
|
117
|
+
FlagPresence,
|
|
118
|
+
FlagSchema,
|
|
119
|
+
InferArg,
|
|
120
|
+
InferArgs,
|
|
121
|
+
InferFlag,
|
|
122
|
+
InferFlags,
|
|
123
|
+
InputPromptConfig,
|
|
124
|
+
InteractiveParams,
|
|
125
|
+
InteractiveResolver,
|
|
126
|
+
InteractiveResult,
|
|
127
|
+
Middleware,
|
|
128
|
+
MiddlewareHandler,
|
|
129
|
+
MiddlewareParams,
|
|
130
|
+
MultiselectPromptConfig,
|
|
131
|
+
Out,
|
|
132
|
+
ProgressHandle,
|
|
133
|
+
ProgressOptions,
|
|
134
|
+
PromptConfig,
|
|
135
|
+
PromptConfigBase,
|
|
136
|
+
PromptKind,
|
|
137
|
+
PromptResult,
|
|
138
|
+
ResolvedArgValue,
|
|
139
|
+
ResolvedValue,
|
|
140
|
+
RunResult,
|
|
141
|
+
SelectChoice,
|
|
142
|
+
SelectPromptConfig,
|
|
143
|
+
SpinnerHandle,
|
|
144
|
+
SpinnerOptions,
|
|
145
|
+
TableColumn,
|
|
146
|
+
TableFormat,
|
|
147
|
+
TableOptions,
|
|
148
|
+
TableStream,
|
|
149
|
+
WithArgPresence,
|
|
150
|
+
WithPresence,
|
|
151
|
+
WithVariadic,
|
|
152
|
+
} from './core/schema/index.ts';
|
|
153
|
+
export {
|
|
154
|
+
ArgBuilder,
|
|
155
|
+
arg,
|
|
156
|
+
CommandBuilder,
|
|
157
|
+
command,
|
|
158
|
+
createArgSchema,
|
|
159
|
+
createSchema,
|
|
160
|
+
FlagBuilder,
|
|
161
|
+
flag,
|
|
162
|
+
group,
|
|
163
|
+
middleware,
|
|
164
|
+
} from './core/schema/index.ts';
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# runtime — Platform abstraction layer
|
|
2
|
+
|
|
3
|
+
Multi-file module. Not truly independent of core — imports `WriteFn` from `core/output/` and
|
|
4
|
+
`ReadFn` from `core/prompt/`.
|
|
5
|
+
|
|
6
|
+
Runtime symbols re-exported from `dreamcli/runtime` subpath (`src/runtime.ts`): `RuntimeAdapter`,
|
|
7
|
+
adapter factories, `ExitError`, detection. `createTestAdapter`/`TestAdapterOptions` are testkit-only
|
|
8
|
+
(exported from `dreamcli/testkit`, not `dreamcli/runtime`).
|
|
9
|
+
|
|
10
|
+
## FILES
|
|
11
|
+
|
|
12
|
+
| File | Status | Lines | Purpose |
|
|
13
|
+
| -------------------- | ---------- | ----: | ------------------------------------------------------------------- |
|
|
14
|
+
| `adapter.ts` | **Active** | 120 | `RuntimeAdapter` interface — process/env/IO abstraction |
|
|
15
|
+
| `auto.ts` | **Active** | 64 | `createAdapter()` — auto-detecting adapter factory |
|
|
16
|
+
| `node.ts` | **Active** | 230 | `createNodeAdapter()` — Node.js implementation |
|
|
17
|
+
| `bun.ts` | **Active** | 20 | `createBunAdapter()` — delegates to Node adapter |
|
|
18
|
+
| `deno.ts` | **Active** | 318 | `createDenoAdapter()` — Deno namespace implementation |
|
|
19
|
+
| `detect.ts` | **Active** | 90 | `detectRuntime()` — Bun/Deno/Node feature detection |
|
|
20
|
+
| `node-builtins.d.ts` | Types | 45 | `@internal` — ambient decls for `node:readline`, `node:fs/promises` |
|
|
21
|
+
| `index.ts` | Barrel | 30 | Re-exports `RuntimeAdapter`, adapters, `ExitError` |
|
|
22
|
+
|
|
23
|
+
## `RuntimeAdapter` INTERFACE
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
argv: string[]
|
|
27
|
+
env: Record<string, string | undefined>
|
|
28
|
+
cwd: string
|
|
29
|
+
stdout: WriteFn
|
|
30
|
+
stderr: WriteFn
|
|
31
|
+
stdin: ReadFn
|
|
32
|
+
exit(code: number): never
|
|
33
|
+
isTTY: boolean
|
|
34
|
+
stdinIsTTY: boolean
|
|
35
|
+
homedir(): string
|
|
36
|
+
configDir(appName: string): string
|
|
37
|
+
readFile(path: string): Promise<string>
|
|
38
|
+
joinPath(...segments: string[]): string
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## ADDING A NEW PLATFORM
|
|
42
|
+
|
|
43
|
+
1. Implement `RuntimeAdapter` in `{platform}.ts`
|
|
44
|
+
2. Add factory `create{Platform}Adapter()` to barrel
|
|
45
|
+
3. Add detection case in `detect.ts`
|
|
46
|
+
4. Wire auto-detection in `auto.ts`
|
|
47
|
+
5. Re-export from `src/runtime.ts`
|
|
48
|
+
|
|
49
|
+
## TEST FILES (5)
|
|
50
|
+
|
|
51
|
+
| File | Tests |
|
|
52
|
+
| ----------------- | --------------------------------------------------------- |
|
|
53
|
+
| `runtime.test.ts` | Node adapter, test adapter, `ExitError`, adapter contract |
|
|
54
|
+
| `detect.test.ts` | Runtime detection logic (globalThis feature probing) |
|
|
55
|
+
| `bun.test.ts` | Bun adapter delegation |
|
|
56
|
+
| `deno.test.ts` | Deno adapter (mock namespace, permission handling, stdin) |
|
|
57
|
+
| `auto.test.ts` | Auto-detecting adapter factory |
|
|
58
|
+
|
|
59
|
+
## GOTCHAS
|
|
60
|
+
|
|
61
|
+
- `globalThis as unknown as GlobalForDetect` in `detect.ts` — runtime boundary, justified cast
|
|
62
|
+
- `node.ts` has 7 `@internal` symbols: `NodeProcess`, `NodeSystemError`, `getNodeProcess`,
|
|
63
|
+
`isNodeSystemError`, `createNodeReadLine`, `resolveHomedir`, `resolveConfigDir`
|
|
64
|
+
- `createTestAdapter()` exported from `dreamcli/testkit` only, not `dreamcli/runtime`
|
|
65
|
+
- `ExitError` thrown by `adapter.exit()` — caught by CLI dispatch layer
|
|
66
|
+
- Empty-string env var fallbacks treated as unset in `node.ts`
|
|
67
|
+
- Win32 paths: `resolveConfigDir` strips trailing separator, `resolveHomedir` has
|
|
68
|
+
`HOMEDRIVE`+`HOMEPATH` fallback
|
|
69
|
+
- `deno.ts` has 7 `@internal` symbols: `DenoNamespace`, `isDenoErrorNamed`, `safeEnvToObject`,
|
|
70
|
+
`safeCwd`, `getDenoNamespace`, `readDenoStdinLine`, `resolveDenoHomedir`, `resolveDenoConfigDir`
|
|
71
|
+
- Deno.args pre-strips binary/script — adapter prepends synthetic `['deno', 'run']` for argv parity
|
|
72
|
+
- Permission-safe: env/cwd catch `PermissionDenied`, readFile returns null for both `NotFound` and
|
|
73
|
+
`PermissionDenied`
|
|
74
|
+
- Deno/web globals used by `deno.ts` come from `deno.jsonc` (`lib: ["deno.ns", "deno.shared_globals"]`)
|