@kjanat/dreamcli 3.0.0-rc.1 → 3.0.0-rc.11
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 +227 -1
- package/dist/core/cli/dispatch.d.mts +6 -5
- package/dist/core/cli/dispatch.mjs +205 -1
- package/dist/core/cli/help-links.d.mts +0 -1
- package/dist/core/cli/help-links.mjs +41 -1
- package/dist/core/cli/index.d.mts +81 -8
- package/dist/core/cli/index.mjs +945 -1
- package/dist/core/cli/planner.d.mts +5 -1
- package/dist/core/cli/planner.mjs +300 -1
- package/dist/core/cli/plugin.d.mts +1 -1
- package/dist/core/cli/plugin.mjs +41 -1
- package/dist/core/cli/propagate.d.mts +1 -1
- package/dist/core/cli/propagate.mjs +57 -1
- package/dist/core/cli/root-help.d.mts +2 -1
- package/dist/core/cli/root-help.mjs +226 -4
- package/dist/core/cli/root-surface.d.mts +12 -1
- package/dist/core/cli/root-surface.mjs +28 -1
- package/dist/core/cli/runtime-preflight.d.mts +14 -2
- package/dist/core/cli/runtime-preflight.mjs +169 -1
- package/dist/core/completion/index.d.mts +0 -1
- package/dist/core/completion/index.mjs +90 -1
- package/dist/core/completion/shells/bash.d.mts +0 -1
- package/dist/core/completion/shells/bash.mjs +308 -3
- package/dist/core/completion/shells/fish.d.mts +0 -1
- package/dist/core/completion/shells/fish.mjs +162 -2
- package/dist/core/completion/shells/powershell.d.mts +0 -1
- package/dist/core/completion/shells/powershell.mjs +358 -2
- package/dist/core/completion/shells/shared.d.mts +13 -2
- package/dist/core/completion/shells/shared.mjs +176 -1
- package/dist/core/completion/shells/zsh.d.mts +0 -1
- package/dist/core/completion/shells/zsh.mjs +251 -2
- package/dist/core/config/index.d.mts +2 -3
- package/dist/core/config/index.mjs +246 -1
- package/dist/core/config/package-json.d.mts +27 -4
- package/dist/core/config/package-json.mjs +386 -3
- package/dist/core/errors/index.d.mts +3 -3
- package/dist/core/errors/index.mjs +87 -1
- package/dist/core/execution/index.d.mts +0 -1
- package/dist/core/execution/index.mjs +201 -1
- package/dist/core/help/ansi.d.mts +11 -5
- package/dist/core/help/ansi.mjs +121 -2
- package/dist/core/help/index.d.mts +22 -3
- package/dist/core/help/index.mjs +341 -7
- package/dist/core/help/theme.d.mts +68 -0
- package/dist/core/help/theme.mjs +46 -0
- package/dist/core/json-schema/index.d.mts +15 -2
- package/dist/core/json-schema/index.mjs +536 -12
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +55 -38
- package/dist/core/json-schema/meta-descriptions.generated.mjs +102 -28
- package/dist/core/output/activity.d.mts +0 -1
- package/dist/core/output/activity.mjs +452 -1
- package/dist/core/output/bind.mjs +56 -1
- package/dist/core/output/contracts.d.mts +4 -5
- package/dist/core/output/contracts.mjs +57 -1
- package/dist/core/output/display-value.mjs +32 -1
- package/dist/core/output/index.d.mts +21 -1
- package/dist/core/output/index.mjs +442 -2
- package/dist/core/output/renderers.d.mts +0 -1
- package/dist/core/output/renderers.mjs +46 -1
- package/dist/core/output/writer.mjs +12 -1
- package/dist/core/parse/index.d.mts +40 -7
- package/dist/core/parse/index.mjs +727 -1
- package/dist/core/prompt/index.d.mts +1 -1
- package/dist/core/prompt/index.mjs +348 -6
- package/dist/core/resolve/args.d.mts +1 -1
- package/dist/core/resolve/args.mjs +105 -1
- package/dist/core/resolve/coerce.d.mts +1 -1
- package/dist/core/resolve/coerce.mjs +336 -1
- package/dist/core/resolve/config.mjs +19 -1
- package/dist/core/resolve/contracts.d.mts +9 -4
- package/dist/core/resolve/errors.d.mts +0 -1
- package/dist/core/resolve/errors.mjs +140 -2
- package/dist/core/resolve/flags.d.mts +7 -2
- package/dist/core/resolve/flags.mjs +251 -1
- package/dist/core/resolve/index.d.mts +2 -2
- package/dist/core/resolve/index.mjs +85 -1
- package/dist/core/resolve/property.d.mts +4 -2
- package/dist/core/resolve/property.mjs +53 -1
- package/dist/core/schema/activity.d.mts +31 -11
- package/dist/core/schema/arg.d.mts +3 -4
- package/dist/core/schema/arg.mjs +463 -1
- package/dist/core/schema/command.d.mts +26 -6
- package/dist/core/schema/command.mjs +726 -1
- package/dist/core/schema/flag.d.mts +485 -19
- package/dist/core/schema/flag.mjs +705 -1
- package/dist/core/schema/index.d.mts +4 -2
- package/dist/core/schema/middleware.d.mts +4 -3
- package/dist/core/schema/middleware.mjs +41 -1
- package/dist/core/schema/number-constraints.mjs +60 -1
- package/dist/core/schema/prompt.d.mts +6 -3
- package/dist/core/schema/run.d.mts +20 -1
- package/dist/core/schema/string-constraints.d.mts +97 -0
- package/dist/core/schema/string-constraints.mjs +69 -0
- package/dist/core/schema/value-parsers.d.mts +78 -0
- package/dist/core/schema/value-parsers.mjs +142 -0
- package/dist/core/schema-dsl/runtime.mjs +271 -2
- package/dist/core/schema-dsl/to-json-schema.d.mts +0 -1
- package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
- package/dist/core/testkit/index.d.mts +0 -31
- package/dist/core/testkit/index.mjs +83 -1
- package/dist/index.d.mts +11 -6
- package/dist/index.mjs +22 -1
- package/dist/runtime/adapter.d.mts +38 -2
- package/dist/runtime/adapter.mjs +87 -1
- package/dist/runtime/auto.d.mts +2 -3
- package/dist/runtime/auto.mjs +45 -1
- package/dist/runtime/deno.d.mts +24 -5
- package/dist/runtime/deno.mjs +262 -2
- package/dist/runtime/detect.mjs +45 -1
- package/dist/runtime/index.d.mts +3 -4
- package/dist/runtime/node.d.mts +8 -2
- package/dist/runtime/node.mjs +220 -2
- package/dist/runtime/paths.mjs +48 -1
- package/dist/runtime.d.mts +4 -4
- package/dist/runtime.mjs +6 -1
- package/dist/strings.mjs +22 -1
- package/dist/testkit.d.mts +1 -0
- package/dist/testkit.mjs +5 -1
- package/dist/version.d.mts +7 -3
- package/dist/version.mjs +7 -1
- package/dreamcli.schema.json +36 -7
- package/package.json +45 -42
- package/dist/runtime/bun.d.mts +0 -28
- package/dist/runtime/bun.mjs +0 -1
- package/src/core/cli/dispatch.ts +0 -355
- package/src/core/cli/help-links.ts +0 -82
- package/src/core/cli/index.ts +0 -1614
- package/src/core/cli/planner.ts +0 -656
- package/src/core/cli/plugin.ts +0 -117
- package/src/core/cli/propagate.ts +0 -97
- package/src/core/cli/root-help.ts +0 -342
- package/src/core/cli/root-surface.ts +0 -87
- package/src/core/cli/runtime-preflight.ts +0 -456
- package/src/core/completion/index.ts +0 -138
- package/src/core/completion/shells/bash.ts +0 -459
- package/src/core/completion/shells/fish.ts +0 -259
- package/src/core/completion/shells/powershell.ts +0 -439
- package/src/core/completion/shells/shared.ts +0 -310
- package/src/core/completion/shells/zsh.ts +0 -381
- package/src/core/config/index.ts +0 -417
- package/src/core/config/package-json.ts +0 -560
- package/src/core/errors/index.ts +0 -193
- package/src/core/execution/index.ts +0 -265
- package/src/core/help/ansi.ts +0 -144
- package/src/core/help/index.ts +0 -563
- package/src/core/json-schema/index.ts +0 -910
- package/src/core/json-schema/meta-descriptions.generated.ts +0 -202
- package/src/core/output/activity.ts +0 -575
- package/src/core/output/bind.ts +0 -59
- package/src/core/output/contracts.ts +0 -194
- package/src/core/output/display-value.ts +0 -48
- package/src/core/output/index.ts +0 -704
- package/src/core/output/renderers.ts +0 -125
- package/src/core/output/writer.ts +0 -46
- package/src/core/parse/index.ts +0 -742
- package/src/core/prompt/index.ts +0 -623
- package/src/core/resolve/args.ts +0 -144
- package/src/core/resolve/coerce.ts +0 -500
- package/src/core/resolve/config.ts +0 -26
- package/src/core/resolve/contracts.ts +0 -135
- package/src/core/resolve/errors.ts +0 -227
- package/src/core/resolve/flags.ts +0 -269
- package/src/core/resolve/index.ts +0 -108
- package/src/core/resolve/property.ts +0 -99
- package/src/core/schema/activity.ts +0 -240
- package/src/core/schema/arg.ts +0 -841
- package/src/core/schema/command.ts +0 -1500
- package/src/core/schema/flag.ts +0 -917
- package/src/core/schema/index.ts +0 -96
- package/src/core/schema/middleware.ts +0 -171
- package/src/core/schema/number-constraints.ts +0 -153
- package/src/core/schema/prompt.ts +0 -171
- package/src/core/schema/run.ts +0 -198
- package/src/core/schema-dsl/index.ts +0 -109
- package/src/core/schema-dsl/parse.ts +0 -262
- package/src/core/schema-dsl/runtime.ts +0 -609
- package/src/core/schema-dsl/to-json-schema.ts +0 -102
- package/src/core/testkit/index.ts +0 -147
- package/src/index.ts +0 -181
- package/src/runtime/adapter.ts +0 -303
- package/src/runtime/auto.ts +0 -86
- package/src/runtime/bun.ts +0 -48
- package/src/runtime/deno.ts +0 -367
- package/src/runtime/detect.ts +0 -105
- package/src/runtime/index.ts +0 -21
- package/src/runtime/node-builtins.d.ts +0 -27
- package/src/runtime/node.ts +0 -289
- package/src/runtime/paths.ts +0 -64
- package/src/runtime/support.ts +0 -77
- package/src/runtime.ts +0 -31
- package/src/schema.ts +0 -16
- package/src/strings.ts +0 -34
- package/src/testkit.ts +0 -25
- package/src/version.ts +0 -20
package/src/core/errors/index.ts
DELETED
|
@@ -1,193 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Structured error types for DreamCLI.
|
|
3
|
-
*
|
|
4
|
-
* Base {@linkcode CLIError} carries stable code, exit code, suggestion, and structured
|
|
5
|
-
* details. {@linkcode ParseError} and {@linkcode ValidationError} derive from it with
|
|
6
|
-
* category-appropriate defaults.
|
|
7
|
-
*
|
|
8
|
-
* @module dreamcli/core/errors
|
|
9
|
-
*/
|
|
10
|
-
|
|
11
|
-
// --- Error codes — discriminated string union per category
|
|
12
|
-
|
|
13
|
-
/** Codes emitted during argv parsing. */
|
|
14
|
-
export type ParseErrorCode =
|
|
15
|
-
| 'UNKNOWN_FLAG'
|
|
16
|
-
| 'UNKNOWN_COMMAND'
|
|
17
|
-
| 'MISSING_VALUE'
|
|
18
|
-
| 'INVALID_VALUE'
|
|
19
|
-
| 'INVALID_SCHEMA'
|
|
20
|
-
| 'UNEXPECTED_POSITIONAL';
|
|
21
|
-
|
|
22
|
-
/** Codes emitted during post-parse validation / resolution. */
|
|
23
|
-
export type ValidationErrorCode =
|
|
24
|
-
| 'REQUIRED_FLAG'
|
|
25
|
-
| 'REQUIRED_ARG'
|
|
26
|
-
| 'INVALID_ENUM'
|
|
27
|
-
| 'TYPE_MISMATCH'
|
|
28
|
-
| 'CONSTRAINT_VIOLATED';
|
|
29
|
-
|
|
30
|
-
/** Any framework error code (extensible via `string & {}`). */
|
|
31
|
-
// deno-lint-ignore ban-types
|
|
32
|
-
export type ErrorCode = ParseErrorCode | ValidationErrorCode | (string & {});
|
|
33
|
-
|
|
34
|
-
// --- Options bag for CLIError construction
|
|
35
|
-
|
|
36
|
-
/** Options accepted by the `CLIError` constructor. */
|
|
37
|
-
export interface CLIErrorOptions {
|
|
38
|
-
/** Stable machine-readable identifier (e.g. `"UNKNOWN_FLAG"`). */
|
|
39
|
-
readonly code: ErrorCode;
|
|
40
|
-
/**
|
|
41
|
-
* Process exit code.
|
|
42
|
-
* @defaultValue `1`
|
|
43
|
-
*/
|
|
44
|
-
readonly exitCode?: number;
|
|
45
|
-
/** One-liner actionable hint shown to the user. */
|
|
46
|
-
readonly suggest?: string;
|
|
47
|
-
/** Arbitrary structured payload (serialised in `--json` mode). */
|
|
48
|
-
readonly details?: Readonly<Record<string, unknown>>;
|
|
49
|
-
/** Original error, if this wraps another. */
|
|
50
|
-
readonly cause?: unknown;
|
|
51
|
-
}
|
|
52
|
-
|
|
53
|
-
// --- CLIError — base structured error
|
|
54
|
-
|
|
55
|
-
/**
|
|
56
|
-
* Base structured error for DreamCLI.
|
|
57
|
-
*
|
|
58
|
-
* Every error surfaced by the framework extends this class, ensuring a
|
|
59
|
-
* consistent shape for rendering (TTY pretty-print, `--json`, test assertions).
|
|
60
|
-
*/
|
|
61
|
-
export class CLIError extends Error {
|
|
62
|
-
/** Error class name, always `'CLIError'` for the base class. @override */
|
|
63
|
-
override readonly name: string = 'CLIError';
|
|
64
|
-
|
|
65
|
-
/** Stable machine-readable identifier. */
|
|
66
|
-
readonly code: ErrorCode;
|
|
67
|
-
|
|
68
|
-
/** Process exit code (defaults to `1`). */
|
|
69
|
-
readonly exitCode: number;
|
|
70
|
-
|
|
71
|
-
/** One-liner actionable hint. */
|
|
72
|
-
readonly suggest: string | undefined;
|
|
73
|
-
|
|
74
|
-
/** Structured payload for machine output. */
|
|
75
|
-
readonly details: Readonly<Record<string, unknown>> | undefined;
|
|
76
|
-
|
|
77
|
-
/** Create a structured CLI error from a human message and machine-readable options. */
|
|
78
|
-
constructor(message: string, options: CLIErrorOptions) {
|
|
79
|
-
super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
|
|
80
|
-
this.code = options.code;
|
|
81
|
-
this.exitCode = options.exitCode ?? 1;
|
|
82
|
-
this.suggest = options.suggest;
|
|
83
|
-
this.details = options.details;
|
|
84
|
-
}
|
|
85
|
-
|
|
86
|
-
/**
|
|
87
|
-
* Serialise to a plain object suitable for JSON output.
|
|
88
|
-
* @sealed
|
|
89
|
-
*/
|
|
90
|
-
toJSON(): CLIErrorJSON {
|
|
91
|
-
return {
|
|
92
|
-
name: this.name,
|
|
93
|
-
code: this.code,
|
|
94
|
-
message: this.message,
|
|
95
|
-
exitCode: this.exitCode,
|
|
96
|
-
...(this.suggest !== undefined && { suggest: this.suggest }),
|
|
97
|
-
...(this.details !== undefined && { details: this.details }),
|
|
98
|
-
};
|
|
99
|
-
}
|
|
100
|
-
}
|
|
101
|
-
|
|
102
|
-
/** Shape returned by {@linkcode CLIError}.toJSON(). */
|
|
103
|
-
export interface CLIErrorJSON {
|
|
104
|
-
/** Error class name (e.g. `'CLIError'`, `'ParseError'`). */
|
|
105
|
-
readonly name: string;
|
|
106
|
-
/** Stable machine-readable identifier for programmatic matching. */
|
|
107
|
-
readonly code: ErrorCode;
|
|
108
|
-
/** Human-readable description of what went wrong. */
|
|
109
|
-
readonly message: string;
|
|
110
|
-
/** Process exit code associated with this error. */
|
|
111
|
-
readonly exitCode: number;
|
|
112
|
-
/** Actionable hint shown to the user, when available. */
|
|
113
|
-
readonly suggest?: string;
|
|
114
|
-
/** Structured payload for machine consumers, when available. */
|
|
115
|
-
readonly details?: Readonly<Record<string, unknown>>;
|
|
116
|
-
}
|
|
117
|
-
|
|
118
|
-
// --- ParseError — argv parsing failures
|
|
119
|
-
|
|
120
|
-
/** Options for {@linkcode ParseError}. Code is narrowed to parse-specific codes. */
|
|
121
|
-
export interface ParseErrorOptions extends Omit<CLIErrorOptions, 'code' | 'exitCode'> {
|
|
122
|
-
/** Parse-category error code (e.g. `'UNKNOWN_FLAG'`, `'MISSING_VALUE'`). */
|
|
123
|
-
readonly code: ParseErrorCode;
|
|
124
|
-
/**
|
|
125
|
-
* Process exit code for parse failures.
|
|
126
|
-
* @defaultValue `2`
|
|
127
|
-
*/
|
|
128
|
-
readonly exitCode?: number;
|
|
129
|
-
}
|
|
130
|
-
|
|
131
|
-
/**
|
|
132
|
-
* Error thrown when argv tokenization / parsing fails.
|
|
133
|
-
*
|
|
134
|
-
* Exit code defaults to `2` (standard for CLI usage errors).
|
|
135
|
-
*/
|
|
136
|
-
export class ParseError extends CLIError {
|
|
137
|
-
/** Always `'ParseError'`. @override */
|
|
138
|
-
override readonly name = 'ParseError' as const;
|
|
139
|
-
/** Narrowed to parse-category codes. */
|
|
140
|
-
declare readonly code: ParseErrorCode;
|
|
141
|
-
|
|
142
|
-
/** Create a parse error with exit code defaulting to `2`. */
|
|
143
|
-
constructor(message: string, options: ParseErrorOptions) {
|
|
144
|
-
super(message, { ...options, exitCode: options.exitCode ?? 2 });
|
|
145
|
-
}
|
|
146
|
-
}
|
|
147
|
-
|
|
148
|
-
// --- ValidationError — post-parse validation / resolution failures
|
|
149
|
-
|
|
150
|
-
/** Options for {@linkcode ValidationError}. Code is narrowed to validation-specific codes. */
|
|
151
|
-
export interface ValidationErrorOptions extends Omit<CLIErrorOptions, 'code' | 'exitCode'> {
|
|
152
|
-
/** Validation-category error code (e.g. `'REQUIRED_FLAG'`, `'INVALID_ENUM'`). */
|
|
153
|
-
readonly code: ValidationErrorCode;
|
|
154
|
-
/**
|
|
155
|
-
* Process exit code for validation failures.
|
|
156
|
-
* @defaultValue `2`
|
|
157
|
-
*/
|
|
158
|
-
readonly exitCode?: number;
|
|
159
|
-
}
|
|
160
|
-
|
|
161
|
-
/**
|
|
162
|
-
* Error thrown when resolved values fail validation constraints.
|
|
163
|
-
*
|
|
164
|
-
* Exit code defaults to `2` (standard for CLI usage errors).
|
|
165
|
-
*/
|
|
166
|
-
export class ValidationError extends CLIError {
|
|
167
|
-
/** Always `'ValidationError'`. @override */
|
|
168
|
-
override readonly name = 'ValidationError' as const;
|
|
169
|
-
/** Narrowed to validation-category codes. */
|
|
170
|
-
declare readonly code: ValidationErrorCode;
|
|
171
|
-
|
|
172
|
-
/** Create a validation error with exit code defaulting to `2`. */
|
|
173
|
-
constructor(message: string, options: ValidationErrorOptions) {
|
|
174
|
-
super(message, { ...options, exitCode: options.exitCode ?? 2 });
|
|
175
|
-
}
|
|
176
|
-
}
|
|
177
|
-
|
|
178
|
-
// --- Type guard utilities
|
|
179
|
-
|
|
180
|
-
/** Narrows an unknown value to `CLIError`. */
|
|
181
|
-
export function isCLIError(value: unknown): value is CLIError {
|
|
182
|
-
return value instanceof CLIError;
|
|
183
|
-
}
|
|
184
|
-
|
|
185
|
-
/** Narrows an unknown value to `ParseError`. */
|
|
186
|
-
export function isParseError(value: unknown): value is ParseError {
|
|
187
|
-
return value instanceof ParseError;
|
|
188
|
-
}
|
|
189
|
-
|
|
190
|
-
/** Narrows an unknown value to `ValidationError`. */
|
|
191
|
-
export function isValidationError(value: unknown): value is ValidationError {
|
|
192
|
-
return value instanceof ValidationError;
|
|
193
|
-
}
|
|
@@ -1,265 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Shared command execution seam.
|
|
3
|
-
*
|
|
4
|
-
* Centralizes the parse -> resolve -> plugin -> handler pipeline so CLI and
|
|
5
|
-
* testkit can converge on one owned execution path during the re-foundation.
|
|
6
|
-
*
|
|
7
|
-
* @module dreamcli/core/execution
|
|
8
|
-
* @internal
|
|
9
|
-
*/
|
|
10
|
-
|
|
11
|
-
import type {
|
|
12
|
-
BeforeParseParams,
|
|
13
|
-
CLIPlugin,
|
|
14
|
-
ResolvedCommandParams,
|
|
15
|
-
} from '#internals/core/cli/plugin.ts';
|
|
16
|
-
import { CLIError } from '#internals/core/errors/index.ts';
|
|
17
|
-
import { formatHelp } from '#internals/core/help/index.ts';
|
|
18
|
-
import type { CapturedOutput } from '#internals/core/output/index.ts';
|
|
19
|
-
import { clearRequestedExitCode, getRequestedExitCode } from '#internals/core/output/index.ts';
|
|
20
|
-
import { includesBeforeSeparator, parse } from '#internals/core/parse/index.ts';
|
|
21
|
-
import { createTestPrompter } from '#internals/core/prompt/index.ts';
|
|
22
|
-
import type { DeprecationWarning, ResolveOptions } from '#internals/core/resolve/index.ts';
|
|
23
|
-
import { resolve } from '#internals/core/resolve/index.ts';
|
|
24
|
-
import type {
|
|
25
|
-
CommandMeta,
|
|
26
|
-
CommandSchema,
|
|
27
|
-
Out,
|
|
28
|
-
RunnableCommand,
|
|
29
|
-
} from '#internals/core/schema/command.ts';
|
|
30
|
-
import type { RunOptions, RunResult } from '#internals/core/schema/run.ts';
|
|
31
|
-
|
|
32
|
-
/**
|
|
33
|
-
* Explicit executor input for a single command invocation.
|
|
34
|
-
* @internal
|
|
35
|
-
*/
|
|
36
|
-
interface CommandExecutionRequest {
|
|
37
|
-
/** The command instance whose handler will be invoked. */
|
|
38
|
-
readonly command: RunnableCommand;
|
|
39
|
-
/** Raw argument tokens to parse (excluding the program name). */
|
|
40
|
-
readonly argv: readonly string[];
|
|
41
|
-
/** Output channel for handler and error rendering. */
|
|
42
|
-
readonly out: Out;
|
|
43
|
-
/** Frozen schema definition (flags, args, metadata) for parsing and resolution. */
|
|
44
|
-
readonly schema: CommandSchema;
|
|
45
|
-
/** Runtime metadata (binary name, version) propagated to the handler. */
|
|
46
|
-
readonly meta: CommandMeta;
|
|
47
|
-
/** Optional overrides for env, config, prompter, plugins, and JSON mode. */
|
|
48
|
-
readonly options?: RunOptions;
|
|
49
|
-
}
|
|
50
|
-
|
|
51
|
-
/**
|
|
52
|
-
* Minimal executor result before output buffers are assembled into `RunResult`.
|
|
53
|
-
* @internal
|
|
54
|
-
*/
|
|
55
|
-
interface CommandExecutionResult {
|
|
56
|
-
/** Process exit code (`0` on success, error-specific otherwise). */
|
|
57
|
-
readonly exitCode: number;
|
|
58
|
-
/** The structured error if the command failed, `undefined` on success. */
|
|
59
|
-
readonly error: CLIError | undefined;
|
|
60
|
-
}
|
|
61
|
-
|
|
62
|
-
/**
|
|
63
|
-
* Run the full parse -> resolve -> plugin -> handler pipeline for one command.
|
|
64
|
-
*
|
|
65
|
-
* Handles `--help` short-circuit, plugin lifecycle hooks, deprecation warnings,
|
|
66
|
-
* and error wrapping. Both CLI dispatch and testkit `runCommand` converge here.
|
|
67
|
-
* @internal
|
|
68
|
-
*/
|
|
69
|
-
async function executeCommand(request: CommandExecutionRequest): Promise<CommandExecutionResult> {
|
|
70
|
-
const { argv, command, meta, options, out, schema } = request;
|
|
71
|
-
clearRequestedExitCode(out);
|
|
72
|
-
|
|
73
|
-
try {
|
|
74
|
-
if (includesBeforeSeparator(argv, '--help') || includesBeforeSeparator(argv, '-h')) {
|
|
75
|
-
const helpText = formatHelp(schema, options?.help);
|
|
76
|
-
out.log(helpText);
|
|
77
|
-
return { exitCode: 0, error: undefined };
|
|
78
|
-
}
|
|
79
|
-
|
|
80
|
-
const handler = command.handler;
|
|
81
|
-
if (handler === undefined) {
|
|
82
|
-
const error = new CLIError(`Command '${command.schema.name}' has no action handler`, {
|
|
83
|
-
code: 'NO_ACTION',
|
|
84
|
-
suggest: `Add an .action() handler to the '${command.schema.name}' command`,
|
|
85
|
-
});
|
|
86
|
-
out.error(error.message);
|
|
87
|
-
return { exitCode: 1, error };
|
|
88
|
-
}
|
|
89
|
-
|
|
90
|
-
await runBeforeParseHooks(options?.plugins, {
|
|
91
|
-
argv,
|
|
92
|
-
command: schema,
|
|
93
|
-
meta,
|
|
94
|
-
out,
|
|
95
|
-
});
|
|
96
|
-
|
|
97
|
-
const parsed = parse(schema, argv);
|
|
98
|
-
|
|
99
|
-
const effectivePrompter =
|
|
100
|
-
options?.prompter ??
|
|
101
|
-
(options?.answers !== undefined ? createTestPrompter(options.answers) : undefined);
|
|
102
|
-
const resolveOptions: ResolveOptions = {
|
|
103
|
-
...(options?.stdinData !== undefined ? { stdinData: options.stdinData } : {}),
|
|
104
|
-
...(options?.env !== undefined ? { env: options.env } : {}),
|
|
105
|
-
...(options?.config !== undefined ? { config: options.config } : {}),
|
|
106
|
-
...(effectivePrompter !== undefined ? { prompter: effectivePrompter } : {}),
|
|
107
|
-
};
|
|
108
|
-
const resolved = await resolve(schema, parsed, resolveOptions);
|
|
109
|
-
const resolvedParams: ResolvedCommandParams = {
|
|
110
|
-
args: resolved.args,
|
|
111
|
-
flags: resolved.flags,
|
|
112
|
-
deprecations: resolved.deprecations,
|
|
113
|
-
command: schema,
|
|
114
|
-
meta,
|
|
115
|
-
out,
|
|
116
|
-
};
|
|
117
|
-
|
|
118
|
-
await runResolvedHooks(options?.plugins, 'afterResolve', resolvedParams);
|
|
119
|
-
|
|
120
|
-
for (const deprecation of resolved.deprecations) {
|
|
121
|
-
out.warn(formatDeprecation(deprecation));
|
|
122
|
-
}
|
|
123
|
-
|
|
124
|
-
await runResolvedHooks(options?.plugins, 'beforeAction', resolvedParams);
|
|
125
|
-
await executeWithExecutionSteps(command, handler, resolved.flags, resolved.args, out, meta);
|
|
126
|
-
await runResolvedHooks(options?.plugins, 'afterAction', resolvedParams);
|
|
127
|
-
|
|
128
|
-
return { exitCode: getRequestedExitCode(out) ?? 0, error: undefined };
|
|
129
|
-
} catch (error: unknown) {
|
|
130
|
-
if (error instanceof CLIError) {
|
|
131
|
-
if (options?.jsonMode === true) {
|
|
132
|
-
out.json({ error: error.toJSON() });
|
|
133
|
-
} else {
|
|
134
|
-
out.error(error.message);
|
|
135
|
-
if (error.suggest !== undefined) {
|
|
136
|
-
out.error(`Suggestion: ${error.suggest}`);
|
|
137
|
-
}
|
|
138
|
-
}
|
|
139
|
-
return { exitCode: error.exitCode, error };
|
|
140
|
-
}
|
|
141
|
-
|
|
142
|
-
const message = error instanceof Error ? error.message : String(error);
|
|
143
|
-
const wrapped = new CLIError(`Unexpected error: ${message}`, {
|
|
144
|
-
code: 'UNEXPECTED_ERROR',
|
|
145
|
-
cause: error,
|
|
146
|
-
});
|
|
147
|
-
if (options?.jsonMode === true) {
|
|
148
|
-
out.json({ error: wrapped.toJSON() });
|
|
149
|
-
} else {
|
|
150
|
-
out.error(wrapped.message);
|
|
151
|
-
}
|
|
152
|
-
return { exitCode: 1, error: wrapped };
|
|
153
|
-
} finally {
|
|
154
|
-
out.stopActive();
|
|
155
|
-
clearRequestedExitCode(out);
|
|
156
|
-
}
|
|
157
|
-
}
|
|
158
|
-
|
|
159
|
-
type ResolvedHookName = Exclude<keyof CLIPlugin['hooks'], 'beforeParse'>;
|
|
160
|
-
|
|
161
|
-
async function runBeforeParseHooks(
|
|
162
|
-
plugins: readonly CLIPlugin[] | undefined,
|
|
163
|
-
params: BeforeParseParams,
|
|
164
|
-
): Promise<void> {
|
|
165
|
-
if (plugins === undefined) return;
|
|
166
|
-
for (const current of plugins) {
|
|
167
|
-
const hook = current.hooks.beforeParse;
|
|
168
|
-
if (hook !== undefined) await hook(params);
|
|
169
|
-
}
|
|
170
|
-
}
|
|
171
|
-
|
|
172
|
-
async function runResolvedHooks(
|
|
173
|
-
plugins: readonly CLIPlugin[] | undefined,
|
|
174
|
-
hookName: ResolvedHookName,
|
|
175
|
-
params: ResolvedCommandParams,
|
|
176
|
-
): Promise<void> {
|
|
177
|
-
if (plugins === undefined) return;
|
|
178
|
-
for (const current of plugins) {
|
|
179
|
-
const hook = current.hooks[hookName];
|
|
180
|
-
if (hook !== undefined) await hook(params);
|
|
181
|
-
}
|
|
182
|
-
}
|
|
183
|
-
|
|
184
|
-
async function executeWithExecutionSteps(
|
|
185
|
-
command: RunnableCommand,
|
|
186
|
-
handler: NonNullable<RunnableCommand['handler']>,
|
|
187
|
-
flags: Readonly<Record<string, unknown>>,
|
|
188
|
-
args: Readonly<Record<string, unknown>>,
|
|
189
|
-
out: Out,
|
|
190
|
-
meta: CommandMeta,
|
|
191
|
-
): Promise<void> {
|
|
192
|
-
const steps = command._executionSteps;
|
|
193
|
-
|
|
194
|
-
type ChainFn = (ctx: Readonly<Record<string, unknown>>) => Promise<void>;
|
|
195
|
-
|
|
196
|
-
let chain: ChainFn = async (ctx) => {
|
|
197
|
-
await handler({ flags, args, ctx, out, meta });
|
|
198
|
-
};
|
|
199
|
-
|
|
200
|
-
for (let i = steps.length - 1; i >= 0; i--) {
|
|
201
|
-
const step = steps[i];
|
|
202
|
-
if (step === undefined) continue;
|
|
203
|
-
const downstream = chain;
|
|
204
|
-
switch (step.kind) {
|
|
205
|
-
case 'derive':
|
|
206
|
-
chain = async (ctx) => {
|
|
207
|
-
const additions = await step.handler({ args, flags, ctx, out, meta });
|
|
208
|
-
if (additions === undefined) {
|
|
209
|
-
await downstream(ctx);
|
|
210
|
-
return;
|
|
211
|
-
}
|
|
212
|
-
if (typeof additions !== 'object' || additions === null || Array.isArray(additions)) {
|
|
213
|
-
throw new CLIError('derive() must return an object or undefined', {
|
|
214
|
-
code: 'INVALID_BUILDER_STATE',
|
|
215
|
-
suggest:
|
|
216
|
-
'Return an object to add context, or return nothing for validation-only derive handlers',
|
|
217
|
-
});
|
|
218
|
-
}
|
|
219
|
-
await downstream({ ...ctx, ...additions });
|
|
220
|
-
};
|
|
221
|
-
break;
|
|
222
|
-
case 'middleware':
|
|
223
|
-
chain = async (ctx) => {
|
|
224
|
-
await step.handler({
|
|
225
|
-
args,
|
|
226
|
-
flags,
|
|
227
|
-
ctx,
|
|
228
|
-
out,
|
|
229
|
-
meta,
|
|
230
|
-
next: async (additions) => {
|
|
231
|
-
await downstream({ ...ctx, ...additions });
|
|
232
|
-
},
|
|
233
|
-
});
|
|
234
|
-
};
|
|
235
|
-
break;
|
|
236
|
-
}
|
|
237
|
-
}
|
|
238
|
-
|
|
239
|
-
await chain({});
|
|
240
|
-
}
|
|
241
|
-
|
|
242
|
-
/**
|
|
243
|
-
* Assemble a {@linkcode CommandExecutionResult} and captured output buffers into a public `RunResult`.
|
|
244
|
-
* @internal
|
|
245
|
-
*/
|
|
246
|
-
function buildRunResult(result: CommandExecutionResult, captured: CapturedOutput): RunResult {
|
|
247
|
-
return {
|
|
248
|
-
exitCode: result.exitCode,
|
|
249
|
-
stdout: captured.stdout,
|
|
250
|
-
stderr: captured.stderr,
|
|
251
|
-
activity: captured.activity,
|
|
252
|
-
error: result.error,
|
|
253
|
-
};
|
|
254
|
-
}
|
|
255
|
-
|
|
256
|
-
function formatDeprecation(deprecation: DeprecationWarning): string {
|
|
257
|
-
const entity =
|
|
258
|
-
deprecation.kind === 'flag' ? `flag --${deprecation.name}` : `argument <${deprecation.name}>`;
|
|
259
|
-
return typeof deprecation.message === 'string'
|
|
260
|
-
? `Warning: ${entity} is deprecated: ${deprecation.message}`
|
|
261
|
-
: `Warning: ${entity} is deprecated`;
|
|
262
|
-
}
|
|
263
|
-
|
|
264
|
-
export type { CommandExecutionRequest, CommandExecutionResult };
|
|
265
|
-
export { buildRunResult, executeCommand };
|
package/src/core/help/ansi.ts
DELETED
|
@@ -1,144 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* ANSI/OSC-aware text helpers for help formatting.
|
|
3
|
-
*
|
|
4
|
-
* Terminal escape sequences (SGR colors, OSC 8 hyperlinks) occupy zero
|
|
5
|
-
* columns when rendered, so width math must measure the *visible* text.
|
|
6
|
-
* {@linkcode visibleWidth} strips escapes before counting, and the shared
|
|
7
|
-
* {@linkcode padEnd}/{@linkcode wrapText} helpers build on it so aligned
|
|
8
|
-
* tables and wrapped lines stay intact when escapes are present.
|
|
9
|
-
*
|
|
10
|
-
* @module dreamcli/core/help/ansi
|
|
11
|
-
*/
|
|
12
|
-
|
|
13
|
-
// --- Escape stripping
|
|
14
|
-
|
|
15
|
-
/**
|
|
16
|
-
* Matches ANSI escape sequences: CSI (e.g. SGR color codes like `\x1b[31m`)
|
|
17
|
-
* and OSC (e.g. OSC 8 hyperlinks), with both BEL and ST terminators.
|
|
18
|
-
*
|
|
19
|
-
* @internal
|
|
20
|
-
*/
|
|
21
|
-
// biome-ignore lint/suspicious/noControlCharactersInRegex: matching terminal escape sequences requires control characters
|
|
22
|
-
const ANSI_PATTERN = /\u001B(?:\[[0-?]*[ -/]*[@-~]|\][^\u0007\u001B]*(?:\u0007|\u001B\\))/g;
|
|
23
|
-
|
|
24
|
-
/**
|
|
25
|
-
* Remove ANSI CSI and OSC escape sequences from `text`.
|
|
26
|
-
*
|
|
27
|
-
* @param text - Text possibly containing terminal escapes.
|
|
28
|
-
* @returns The text with all escape sequences removed.
|
|
29
|
-
*/
|
|
30
|
-
function stripAnsi(text: string): string {
|
|
31
|
-
return text.replace(ANSI_PATTERN, '');
|
|
32
|
-
}
|
|
33
|
-
|
|
34
|
-
/**
|
|
35
|
-
* Measure the visible column width of `text`, ignoring ANSI/OSC escapes.
|
|
36
|
-
*
|
|
37
|
-
* Escape sequences (SGR colors, OSC 8 hyperlinks) occupy zero columns when
|
|
38
|
-
* rendered, so `.length` overcounts whenever they are present. Help
|
|
39
|
-
* formatting uses this for padding and wrapping; exported for custom help
|
|
40
|
-
* renderers that mix colors or links into aligned output.
|
|
41
|
-
*
|
|
42
|
-
* @param text - Text possibly containing terminal escapes.
|
|
43
|
-
* @returns Number of visible characters.
|
|
44
|
-
*
|
|
45
|
-
* @example
|
|
46
|
-
* ```ts
|
|
47
|
-
* visibleWidth('plain'); // 5
|
|
48
|
-
* visibleWidth(osc8('https://x.dev', 'x')); // 1
|
|
49
|
-
* ```
|
|
50
|
-
*/
|
|
51
|
-
function visibleWidth(text: string): number {
|
|
52
|
-
return stripAnsi(text).length;
|
|
53
|
-
}
|
|
54
|
-
|
|
55
|
-
// --- OSC 8 hyperlinks
|
|
56
|
-
|
|
57
|
-
const OSC = '\u001B]';
|
|
58
|
-
const BEL = '\u0007';
|
|
59
|
-
|
|
60
|
-
/**
|
|
61
|
-
* Wrap `text` in an [OSC 8 hyperlink](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda)
|
|
62
|
-
* pointing at `url`.
|
|
63
|
-
*
|
|
64
|
-
* Supporting terminals render `text` as a clickable link; non-supporting
|
|
65
|
-
* terminals ignore the escape sequence and show plain text. Combine with
|
|
66
|
-
* {@linkcode visibleWidth}-aware formatting when embedding links in aligned
|
|
67
|
-
* output.
|
|
68
|
-
*
|
|
69
|
-
* @param url - Link target (string or `URL` instance).
|
|
70
|
-
* @param text - Visible link text.
|
|
71
|
-
* @returns The OSC 8 escape sequence wrapping `text`.
|
|
72
|
-
*
|
|
73
|
-
* @example
|
|
74
|
-
* ```ts
|
|
75
|
-
* cli('mycli').version(osc8('https://github.com/me/mycli/releases/tag/v1.0.0', '1.0.0'));
|
|
76
|
-
* ```
|
|
77
|
-
*/
|
|
78
|
-
function osc8(url: string | URL, text: string): string {
|
|
79
|
-
const href = url instanceof URL ? url.href : url;
|
|
80
|
-
return `${OSC}8;;${href}${BEL}${text}${OSC}8;;${BEL}`;
|
|
81
|
-
}
|
|
82
|
-
|
|
83
|
-
// --- Width-aware padding and wrapping
|
|
84
|
-
|
|
85
|
-
/**
|
|
86
|
-
* Pad `text` to `length` visible columns with trailing spaces.
|
|
87
|
-
*
|
|
88
|
-
* @param text - The string to pad (may contain ANSI/OSC escapes).
|
|
89
|
-
* @param length - Target visible width in columns.
|
|
90
|
-
* @returns The padded string, unchanged if already at or beyond `length`.
|
|
91
|
-
*/
|
|
92
|
-
function padEnd(text: string, length: number): string {
|
|
93
|
-
const visible = visibleWidth(text);
|
|
94
|
-
if (visible >= length) return text;
|
|
95
|
-
return text + ' '.repeat(length - visible);
|
|
96
|
-
}
|
|
97
|
-
|
|
98
|
-
/**
|
|
99
|
-
* Wrap text to `width`, preserving leading indent on continuation lines.
|
|
100
|
-
*
|
|
101
|
-
* Line lengths are measured with {@linkcode visibleWidth}, so embedded
|
|
102
|
-
* ANSI/OSC escapes do not trigger premature wrapping.
|
|
103
|
-
*
|
|
104
|
-
* @param text - The text to wrap.
|
|
105
|
-
* @param width - Maximum line width in columns.
|
|
106
|
-
* @param indent - Number of leading spaces for continuation lines.
|
|
107
|
-
* @returns The wrapped string with newlines inserted as needed.
|
|
108
|
-
*/
|
|
109
|
-
function wrapText(text: string, width: number, indent: number): string {
|
|
110
|
-
if (visibleWidth(text) + indent <= width) return text;
|
|
111
|
-
|
|
112
|
-
const maxLen = width - indent;
|
|
113
|
-
if (maxLen <= 0) return text;
|
|
114
|
-
|
|
115
|
-
const words = text.split(' ');
|
|
116
|
-
const lines: string[] = [];
|
|
117
|
-
let current = '';
|
|
118
|
-
let currentWidth = 0;
|
|
119
|
-
|
|
120
|
-
for (const word of words) {
|
|
121
|
-
const wordWidth = visibleWidth(word);
|
|
122
|
-
if (current.length === 0) {
|
|
123
|
-
current = word;
|
|
124
|
-
currentWidth = wordWidth;
|
|
125
|
-
} else if (currentWidth + 1 + wordWidth <= maxLen) {
|
|
126
|
-
current += ` ${word}`;
|
|
127
|
-
currentWidth += 1 + wordWidth;
|
|
128
|
-
} else {
|
|
129
|
-
lines.push(current);
|
|
130
|
-
current = word;
|
|
131
|
-
currentWidth = wordWidth;
|
|
132
|
-
}
|
|
133
|
-
}
|
|
134
|
-
if (current.length > 0) {
|
|
135
|
-
lines.push(current);
|
|
136
|
-
}
|
|
137
|
-
|
|
138
|
-
const pad = ' '.repeat(indent);
|
|
139
|
-
return lines.map((line, i) => (i === 0 ? line : `${pad}${line}`)).join('\n');
|
|
140
|
-
}
|
|
141
|
-
|
|
142
|
-
// --- Exports
|
|
143
|
-
|
|
144
|
-
export { osc8, padEnd, stripAnsi, visibleWidth, wrapText };
|