@kjanat/dreamcli 3.0.0-rc.6 → 3.0.0-rc.8
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 +94 -1
- package/dist/core/cli/dispatch.d.mts +6 -5
- package/dist/core/cli/dispatch.mjs +7 -5
- package/dist/core/cli/help-links.d.mts +0 -1
- package/dist/core/cli/index.d.mts +27 -2
- package/dist/core/cli/index.mjs +28 -14
- package/dist/core/cli/planner.d.mts +3 -1
- package/dist/core/cli/planner.mjs +12 -12
- package/dist/core/cli/plugin.d.mts +1 -1
- package/dist/core/cli/propagate.d.mts +1 -1
- package/dist/core/cli/root-help.d.mts +0 -1
- package/dist/core/cli/root-help.mjs +38 -21
- package/dist/core/cli/root-surface.d.mts +0 -1
- package/dist/core/cli/runtime-preflight.d.mts +12 -2
- package/dist/core/cli/runtime-preflight.mjs +5 -4
- package/dist/core/completion/index.d.mts +0 -1
- package/dist/core/completion/index.mjs +1 -1
- package/dist/core/completion/shells/bash.d.mts +0 -1
- package/dist/core/completion/shells/bash.mjs +8 -4
- package/dist/core/completion/shells/fish.d.mts +0 -1
- package/dist/core/completion/shells/fish.mjs +6 -3
- package/dist/core/completion/shells/powershell.d.mts +0 -1
- package/dist/core/completion/shells/powershell.mjs +10 -5
- package/dist/core/completion/shells/shared.d.mts +13 -2
- package/dist/core/completion/shells/shared.mjs +24 -2
- package/dist/core/completion/shells/zsh.d.mts +0 -1
- package/dist/core/completion/shells/zsh.mjs +11 -4
- package/dist/core/config/index.d.mts +2 -3
- package/dist/core/config/index.mjs +2 -2
- package/dist/core/config/package-json.d.mts +27 -4
- package/dist/core/config/package-json.mjs +20 -19
- package/dist/core/errors/index.d.mts +1 -1
- package/dist/core/execution/index.d.mts +0 -1
- package/dist/core/execution/index.mjs +8 -4
- package/dist/core/help/ansi.mjs +3 -2
- package/dist/core/help/index.d.mts +22 -3
- package/dist/core/help/index.mjs +65 -53
- 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 +1 -1
- package/dist/core/json-schema/index.mjs +39 -8
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +22 -5
- package/dist/core/json-schema/meta-descriptions.generated.mjs +14 -5
- package/dist/core/output/activity.d.mts +0 -1
- package/dist/core/output/contracts.d.mts +0 -1
- package/dist/core/output/contracts.mjs +1 -1
- package/dist/core/output/index.d.mts +0 -1
- package/dist/core/output/index.mjs +1 -1
- package/dist/core/output/renderers.d.mts +0 -1
- package/dist/core/parse/index.d.mts +40 -7
- package/dist/core/parse/index.mjs +209 -40
- package/dist/core/prompt/index.d.mts +1 -0
- package/dist/core/resolve/args.d.mts +1 -1
- package/dist/core/resolve/coerce.d.mts +1 -1
- package/dist/core/resolve/coerce.mjs +71 -14
- package/dist/core/resolve/contracts.d.mts +7 -2
- package/dist/core/resolve/errors.d.mts +0 -1
- package/dist/core/resolve/flags.d.mts +7 -2
- package/dist/core/resolve/flags.mjs +61 -6
- package/dist/core/resolve/index.d.mts +2 -2
- package/dist/core/resolve/index.mjs +1 -1
- package/dist/core/resolve/property.d.mts +3 -0
- package/dist/core/resolve/property.mjs +11 -3
- package/dist/core/schema/activity.d.mts +31 -11
- package/dist/core/schema/arg.d.mts +1 -2
- package/dist/core/schema/command.d.mts +8 -6
- package/dist/core/schema/command.mjs +26 -12
- package/dist/core/schema/flag.d.mts +439 -10
- package/dist/core/schema/flag.mjs +255 -3
- package/dist/core/schema/index.d.mts +4 -2
- package/dist/core/schema/middleware.d.mts +4 -3
- package/dist/core/schema/prompt.d.mts +5 -2
- 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/to-json-schema.d.mts +0 -1
- package/dist/core/testkit/index.d.mts +0 -31
- package/dist/core/testkit/index.mjs +1 -1
- package/dist/index.d.mts +8 -4
- package/dist/index.mjs +7 -7
- package/dist/runtime/adapter.d.mts +22 -1
- package/dist/runtime/adapter.mjs +3 -0
- package/dist/runtime/auto.d.mts +0 -1
- package/dist/runtime/deno.d.mts +15 -5
- package/dist/runtime/deno.mjs +9 -0
- package/dist/runtime/node.d.mts +2 -2
- package/dist/runtime/node.mjs +10 -0
- package/dist/runtime.d.mts +1 -0
- package/dist/testkit.d.mts +1 -0
- package/dist/version.mjs +2 -2
- package/dreamcli.schema.json +35 -6
- package/package.json +12 -13
|
@@ -1,5 +1,6 @@
|
|
|
1
|
-
import { describeNumberConstraintViolation, validateNumberConstraints } from "../schema/number-constraints.mjs";
|
|
2
1
|
import { ValidationError } from "../errors/index.mjs";
|
|
2
|
+
import { describeNumberConstraintViolation, validateNumberConstraints } from "../schema/number-constraints.mjs";
|
|
3
|
+
import { describeStringConstraintViolation, validateStringConstraints } from "../schema/string-constraints.mjs";
|
|
3
4
|
import { toSharedArgPropertySchema, toSharedFlagPropertySchema } from "./property.mjs";
|
|
4
5
|
//#region src/core/resolve/coerce.ts
|
|
5
6
|
function sourceLabel(source) {
|
|
@@ -62,6 +63,36 @@ function finalizeNumber(flagName, source, raw, value, constraints) {
|
|
|
62
63
|
})
|
|
63
64
|
};
|
|
64
65
|
}
|
|
66
|
+
/**
|
|
67
|
+
* Apply string constraints to an already-string value. Shares the single
|
|
68
|
+
* {@link validateStringConstraints} check used by the parse path, so the two
|
|
69
|
+
* boundaries cannot drift. On violation, returns a `CONSTRAINT_VIOLATED`
|
|
70
|
+
* failure mirroring {@link finalizeNumber}.
|
|
71
|
+
*/
|
|
72
|
+
function finalizeString(flagName, source, value, constraints) {
|
|
73
|
+
const violation = validateStringConstraints(value, constraints);
|
|
74
|
+
if (violation === void 0) return {
|
|
75
|
+
ok: true,
|
|
76
|
+
value
|
|
77
|
+
};
|
|
78
|
+
const reason = describeStringConstraintViolation(violation);
|
|
79
|
+
return {
|
|
80
|
+
ok: false,
|
|
81
|
+
error: new ValidationError(`Invalid value '${value}' ${sourceLabel(source)} for flag --${flagName}: ${reason}`, {
|
|
82
|
+
code: "CONSTRAINT_VIOLATED",
|
|
83
|
+
details: {
|
|
84
|
+
flag: flagName,
|
|
85
|
+
...sourceDetails(source),
|
|
86
|
+
value,
|
|
87
|
+
expected: "string",
|
|
88
|
+
constraint: violation.kind,
|
|
89
|
+
..."bound" in violation ? { bound: violation.bound } : {},
|
|
90
|
+
..."pattern" in violation ? { pattern: violation.pattern } : {}
|
|
91
|
+
},
|
|
92
|
+
suggest: source.kind === "env" ? `Set ${source.envVar} to a valid string` : source.kind === "config" ? `Set ${source.configPath} to a valid string in your config` : `Enter a valid value for --${flagName}`
|
|
93
|
+
})
|
|
94
|
+
};
|
|
95
|
+
}
|
|
65
96
|
/** Coerce a raw value from env/config/prompt into the type declared by a flag schema. */
|
|
66
97
|
function coerceValue(flagName, source, raw, schema) {
|
|
67
98
|
const sharedSchema = toSharedFlagPropertySchema(schema);
|
|
@@ -108,7 +139,7 @@ function coerceValue(flagName, source, raw, schema) {
|
|
|
108
139
|
ok: true,
|
|
109
140
|
value: []
|
|
110
141
|
};
|
|
111
|
-
const parts = raw.split(",");
|
|
142
|
+
const parts = raw.split(schema.separator ?? ",").filter((part) => part.length > 0);
|
|
112
143
|
if (schema.elementSchema) {
|
|
113
144
|
const coerced = [];
|
|
114
145
|
for (const part of parts) {
|
|
@@ -127,24 +158,50 @@ function coerceValue(flagName, source, raw, schema) {
|
|
|
127
158
|
};
|
|
128
159
|
}
|
|
129
160
|
return coercionError(flagName, source, "TYPE_MISMATCH", "array", raw, "Invalid array value", source.kind === "env" ? `Set ${source.envVar} to comma-separated values` : source.kind === "config" ? `Set ${source.configPath} to an array in your config` : `Provide valid values for --${flagName}`);
|
|
161
|
+
case "count": {
|
|
162
|
+
const value = typeof raw === "string" ? raw.trim() === "" ? NaN : Number(raw) : raw;
|
|
163
|
+
if (typeof value === "number" && Number.isInteger(value) && value >= 0) return {
|
|
164
|
+
ok: true,
|
|
165
|
+
value
|
|
166
|
+
};
|
|
167
|
+
return coercionError(flagName, source, "TYPE_MISMATCH", "count", raw, typeof raw === "string" ? `Invalid count value '${raw}'` : "Invalid count value", source.kind === "env" ? `Set ${source.envVar} to a non-negative integer` : source.kind === "config" ? `Set ${source.configPath} to a non-negative integer in your config` : `Enter a non-negative integer for --${flagName}`);
|
|
168
|
+
}
|
|
169
|
+
case "keyValue":
|
|
170
|
+
if (isStringRecord(raw)) return {
|
|
171
|
+
ok: true,
|
|
172
|
+
value: { ...raw }
|
|
173
|
+
};
|
|
174
|
+
if (typeof raw === "string") {
|
|
175
|
+
if (raw === "") return {
|
|
176
|
+
ok: true,
|
|
177
|
+
value: {}
|
|
178
|
+
};
|
|
179
|
+
const pairs = [];
|
|
180
|
+
for (const pair of raw.split(",").filter((segment) => segment.length > 0)) {
|
|
181
|
+
const eq = pair.indexOf("=");
|
|
182
|
+
if (eq <= 0) return coercionError(flagName, source, "TYPE_MISMATCH", "key=value", raw, `Invalid key-value pair '${pair}'`, source.kind === "env" ? `Set ${source.envVar} to comma-separated KEY=VALUE pairs` : source.kind === "config" ? `Set ${source.configPath} to an object with string values` : `Use KEY=VALUE for --${flagName}`);
|
|
183
|
+
pairs.push([pair.slice(0, eq), pair.slice(eq + 1)]);
|
|
184
|
+
}
|
|
185
|
+
return {
|
|
186
|
+
ok: true,
|
|
187
|
+
value: Object.fromEntries(pairs)
|
|
188
|
+
};
|
|
189
|
+
}
|
|
190
|
+
return coercionError(flagName, source, "TYPE_MISMATCH", "key=value", raw, "Invalid key-value value", source.kind === "env" ? `Set ${source.envVar} to comma-separated KEY=VALUE pairs` : source.kind === "config" ? `Set ${source.configPath} to an object with string values` : `Use KEY=VALUE for --${flagName}`);
|
|
130
191
|
}
|
|
131
192
|
throw new Error(`Unreachable flag coercion kind: ${schema.kind}`);
|
|
132
193
|
}
|
|
194
|
+
/** Narrow config-sourced objects to plain string-valued records. */
|
|
195
|
+
function isStringRecord(value) {
|
|
196
|
+
if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
|
|
197
|
+
return Object.values(value).every((entry) => typeof entry === "string");
|
|
198
|
+
}
|
|
133
199
|
function coerceSharedPropertyValue(flagName, source, raw, schema) {
|
|
134
200
|
switch (schema.kind) {
|
|
135
201
|
case "string":
|
|
136
|
-
if (typeof raw === "string") return
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
};
|
|
140
|
-
if (source.kind === "prompt") return {
|
|
141
|
-
ok: true,
|
|
142
|
-
value: String(raw)
|
|
143
|
-
};
|
|
144
|
-
if (source.kind === "config" && (typeof raw === "number" || typeof raw === "boolean")) return {
|
|
145
|
-
ok: true,
|
|
146
|
-
value: String(raw)
|
|
147
|
-
};
|
|
202
|
+
if (typeof raw === "string") return finalizeString(flagName, source, raw, schema.stringConstraints);
|
|
203
|
+
if (source.kind === "prompt") return finalizeString(flagName, source, String(raw), schema.stringConstraints);
|
|
204
|
+
if (source.kind === "config" && (typeof raw === "number" || typeof raw === "boolean")) return finalizeString(flagName, source, String(raw), schema.stringConstraints);
|
|
148
205
|
return coercionError(flagName, source, "TYPE_MISMATCH", "string", raw, "Invalid string value", source.kind === "config" ? `Set ${source.configPath} to a string in your config` : `Enter a valid string for --${flagName}`);
|
|
149
206
|
case "number":
|
|
150
207
|
if (typeof raw === "number") {
|
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
import { ParseResult } from "../parse/index.mjs";
|
|
2
1
|
import { PromptEngine } from "../prompt/index.mjs";
|
|
3
2
|
import { CommandSchema } from "../schema/command.mjs";
|
|
4
|
-
|
|
3
|
+
import "../schema/index.mjs";
|
|
4
|
+
import { ParseResult } from "../parse/index.mjs";
|
|
5
5
|
//#region src/core/resolve/contracts.d.ts
|
|
6
6
|
/** Ordered flag resolution stages owned by the resolver. */
|
|
7
7
|
declare const FLAG_RESOLUTION_ORDER: readonly ['cli', 'env', 'config', 'prompt', 'default'];
|
|
@@ -48,6 +48,11 @@ interface ResolveOptions {
|
|
|
48
48
|
readonly config?: Readonly<Record<string, unknown>>;
|
|
49
49
|
/** Interactive prompt engine; absent in non-TTY / CI contexts. */
|
|
50
50
|
readonly prompter?: PromptEngine;
|
|
51
|
+
/**
|
|
52
|
+
* Filesystem probe for `flag.path()` checks: what exists at the path, or
|
|
53
|
+
* `null` when nothing does. When absent, path checks are skipped.
|
|
54
|
+
*/
|
|
55
|
+
readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
|
|
51
56
|
}
|
|
52
57
|
/** Structured deprecation notice emitted for explicitly sourced values. */
|
|
53
58
|
interface DeprecationWarning {
|
|
@@ -3,10 +3,15 @@ import { FlagKind, FlagSchema } from "../schema/flag.mjs";
|
|
|
3
3
|
import { PromptEngine } from "../prompt/index.mjs";
|
|
4
4
|
import { DeprecationWarning } from "./contracts.mjs";
|
|
5
5
|
import { ErasedInteractiveResolver } from "../schema/command.mjs";
|
|
6
|
-
|
|
7
6
|
//#region src/core/resolve/flags.d.ts
|
|
7
|
+
/**
|
|
8
|
+
* Filesystem probe injected by the caller for `flag.path()` checks.
|
|
9
|
+
*
|
|
10
|
+
* Returns what exists at the path, or `null` when nothing does.
|
|
11
|
+
*/
|
|
12
|
+
type StatFn = (path: string) => Promise<'file' | 'directory' | null>;
|
|
8
13
|
/** Walk every declared flag through the resolution chain (cli -> env -> config -> prompt -> default), collecting deprecations and throwing aggregated errors. */
|
|
9
|
-
declare function resolveFlags(flagSchemas: Readonly<Record<string, FlagSchema>>, parsedFlags: Readonly<Record<string, unknown>>, env: Readonly<Record<string, string | undefined>>, config: Readonly<Record<string, unknown>>, prompter: PromptEngine | undefined, interactive: ErasedInteractiveResolver | undefined, deprecations: DeprecationWarning[]): Promise<Readonly<Record<string, unknown>>>;
|
|
14
|
+
declare function resolveFlags(flagSchemas: Readonly<Record<string, FlagSchema>>, parsedFlags: Readonly<Record<string, unknown>>, env: Readonly<Record<string, string | undefined>>, config: Readonly<Record<string, unknown>>, prompter: PromptEngine | undefined, interactive: ErasedInteractiveResolver | undefined, deprecations: DeprecationWarning[], stat: StatFn | undefined): Promise<Readonly<Record<string, unknown>>>;
|
|
10
15
|
/** Maps each flag kind to the prompt kinds that produce compatible values. */
|
|
11
16
|
declare const COMPATIBLE_PROMPT_KINDS: Record<FlagKind, readonly PromptKind[]>;
|
|
12
17
|
//#endregion
|
|
@@ -11,7 +11,7 @@ import { resolveConfigPath } from "./config.mjs";
|
|
|
11
11
|
* @internal
|
|
12
12
|
*/
|
|
13
13
|
/** Walk every declared flag through the resolution chain (cli -> env -> config -> prompt -> default), collecting deprecations and throwing aggregated errors. */
|
|
14
|
-
async function resolveFlags(flagSchemas, parsedFlags, env, config, prompter, interactive, deprecations) {
|
|
14
|
+
async function resolveFlags(flagSchemas, parsedFlags, env, config, prompter, interactive, deprecations, stat) {
|
|
15
15
|
const resolved = {};
|
|
16
16
|
const errors = [];
|
|
17
17
|
const hardErrorFlags = /* @__PURE__ */ new Set();
|
|
@@ -101,6 +101,10 @@ async function resolveFlags(flagSchemas, parsedFlags, env, config, prompter, int
|
|
|
101
101
|
resolved[name] = [];
|
|
102
102
|
continue;
|
|
103
103
|
}
|
|
104
|
+
if (schema.kind === "keyValue" && schema.presence !== "required") {
|
|
105
|
+
resolved[name] = {};
|
|
106
|
+
continue;
|
|
107
|
+
}
|
|
104
108
|
if (schema.presence === "required") {
|
|
105
109
|
const details = {
|
|
106
110
|
flag: name,
|
|
@@ -117,9 +121,46 @@ async function resolveFlags(flagSchemas, parsedFlags, env, config, prompter, int
|
|
|
117
121
|
}
|
|
118
122
|
resolved[name] = void 0;
|
|
119
123
|
}
|
|
124
|
+
for (const [name, schema] of Object.entries(flagSchemas)) {
|
|
125
|
+
const value = resolved[name];
|
|
126
|
+
if (schema.kind === "array" && schema.unique && Array.isArray(value)) resolved[name] = [...new Set(value)];
|
|
127
|
+
if (schema.pathChecks !== void 0 && typeof value === "string" && stat !== void 0) {
|
|
128
|
+
const violation = await validatePathChecks(name, value, schema.pathChecks, stat);
|
|
129
|
+
if (violation !== void 0) errors.push(violation);
|
|
130
|
+
}
|
|
131
|
+
}
|
|
120
132
|
if (isNonEmpty(errors)) throwAggregatedErrors(errors);
|
|
121
133
|
return resolved;
|
|
122
134
|
}
|
|
135
|
+
/**
|
|
136
|
+
* Check a resolved path value against its declared filesystem expectations.
|
|
137
|
+
*
|
|
138
|
+
* @returns `undefined` when the path satisfies the checks, or a
|
|
139
|
+
* {@link ValidationError} with code `'CONSTRAINT_VIOLATED'` otherwise.
|
|
140
|
+
* @internal
|
|
141
|
+
*/
|
|
142
|
+
async function validatePathChecks(flagName, value, checks, stat) {
|
|
143
|
+
const found = await stat(value);
|
|
144
|
+
if (found === null) return new ValidationError(`Path '${value}' for flag --${flagName} does not exist`, {
|
|
145
|
+
code: "CONSTRAINT_VIOLATED",
|
|
146
|
+
details: {
|
|
147
|
+
flag: flagName,
|
|
148
|
+
value,
|
|
149
|
+
constraint: "mustExist"
|
|
150
|
+
},
|
|
151
|
+
suggest: `Provide an existing path for --${flagName}`
|
|
152
|
+
});
|
|
153
|
+
if (checks.type !== void 0 && found !== checks.type) return new ValidationError(`Path '${value}' for flag --${flagName} is a ${found}, expected a ${checks.type}`, {
|
|
154
|
+
code: "CONSTRAINT_VIOLATED",
|
|
155
|
+
details: {
|
|
156
|
+
flag: flagName,
|
|
157
|
+
value,
|
|
158
|
+
constraint: "pathType",
|
|
159
|
+
expected: checks.type
|
|
160
|
+
},
|
|
161
|
+
suggest: `Provide a ${checks.type} path for --${flagName}`
|
|
162
|
+
});
|
|
163
|
+
}
|
|
123
164
|
/** Maps each flag kind to the prompt kinds that produce compatible values. */
|
|
124
165
|
const COMPATIBLE_PROMPT_KINDS = {
|
|
125
166
|
boolean: ["confirm"],
|
|
@@ -132,7 +173,9 @@ const COMPATIBLE_PROMPT_KINDS = {
|
|
|
132
173
|
"select",
|
|
133
174
|
"confirm",
|
|
134
175
|
"multiselect"
|
|
135
|
-
]
|
|
176
|
+
],
|
|
177
|
+
count: [],
|
|
178
|
+
keyValue: []
|
|
136
179
|
};
|
|
137
180
|
/**
|
|
138
181
|
* Check whether a prompt kind is compatible with the flag's declared kind.
|
|
@@ -144,7 +187,18 @@ const COMPATIBLE_PROMPT_KINDS = {
|
|
|
144
187
|
function validatePromptFlagCompatibility(flagName, flagKind, promptKind) {
|
|
145
188
|
const allowed = COMPATIBLE_PROMPT_KINDS[flagKind];
|
|
146
189
|
if (allowed.includes(promptKind)) return void 0;
|
|
147
|
-
|
|
190
|
+
const first = allowed[0];
|
|
191
|
+
if (first === void 0) return new ValidationError(`Prompt kind '${promptKind}' is not compatible with ${flagKind} flag --${flagName}. ${flagKind} flags are not promptable`, {
|
|
192
|
+
code: "CONSTRAINT_VIOLATED",
|
|
193
|
+
details: {
|
|
194
|
+
flag: flagName,
|
|
195
|
+
flagKind,
|
|
196
|
+
promptKind,
|
|
197
|
+
allowed
|
|
198
|
+
},
|
|
199
|
+
suggest: `Remove the prompt config for --${flagName}`
|
|
200
|
+
});
|
|
201
|
+
return new ValidationError(`Prompt kind '${promptKind}' is not compatible with ${flagKind} flag --${flagName}. Use '${first}' instead`, {
|
|
148
202
|
code: "CONSTRAINT_VIOLATED",
|
|
149
203
|
details: {
|
|
150
204
|
flag: flagName,
|
|
@@ -152,7 +206,7 @@ function validatePromptFlagCompatibility(flagName, flagKind, promptKind) {
|
|
|
152
206
|
promptKind,
|
|
153
207
|
allowed
|
|
154
208
|
},
|
|
155
|
-
suggest: `Change the prompt to { kind: '${
|
|
209
|
+
suggest: `Change the prompt to { kind: '${first}' } for --${flagName}`
|
|
156
210
|
});
|
|
157
211
|
}
|
|
158
212
|
/**
|
|
@@ -184,7 +238,8 @@ async function resolvePromptValueWithConfig(flagName, schema, promptConfig, prom
|
|
|
184
238
|
/** Build a human-readable suggestion listing all available sources for a required flag. @internal */
|
|
185
239
|
function buildRequiredFlagSuggest(name, schema) {
|
|
186
240
|
const sources = [];
|
|
187
|
-
|
|
241
|
+
const takesValue = schema.kind !== "boolean" && schema.kind !== "count";
|
|
242
|
+
sources.push(`Provide --${name}${takesValue ? " <value>" : ""}`);
|
|
188
243
|
if (schema.envVar !== void 0) sources.push(`set ${schema.envVar}`);
|
|
189
244
|
if (schema.configPath !== void 0) sources.push(`add ${schema.configPath} to config`);
|
|
190
245
|
if (sources.length <= 1) return sources.join("");
|
|
@@ -193,4 +248,4 @@ function buildRequiredFlagSuggest(name, schema) {
|
|
|
193
248
|
return sources.length === 2 ? `${rest.join("")} or ${last}` : `${rest.join(", ")}, or ${last}`;
|
|
194
249
|
}
|
|
195
250
|
//#endregion
|
|
196
|
-
export { resolveFlags };
|
|
251
|
+
export { COMPATIBLE_PROMPT_KINDS, resolveFlags };
|
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
import { ParseResult } from "../parse/index.mjs";
|
|
2
1
|
import { DeprecationWarning, ResolveOptions, ResolveResult } from "./contracts.mjs";
|
|
3
2
|
import { CommandSchema } from "../schema/command.mjs";
|
|
4
|
-
|
|
3
|
+
import "../schema/index.mjs";
|
|
4
|
+
import { ParseResult } from "../parse/index.mjs";
|
|
5
5
|
//#region src/core/resolve/index.d.ts
|
|
6
6
|
/**
|
|
7
7
|
* Resolve parsed values against a command schema.
|
|
@@ -63,7 +63,7 @@ async function resolve(schema, parsed, options) {
|
|
|
63
63
|
let args = {};
|
|
64
64
|
const errors = [];
|
|
65
65
|
try {
|
|
66
|
-
flags = await resolveFlags(schema.flags, parsed.flags, env, config, prompter, schema.interactive, deprecations);
|
|
66
|
+
flags = await resolveFlags(schema.flags, parsed.flags, env, config, prompter, schema.interactive, deprecations, options?.stat);
|
|
67
67
|
} catch (error) {
|
|
68
68
|
if (!isValidationError(error)) throw error;
|
|
69
69
|
errors.push(...collectValidationErrors(error));
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import { NumberConstraints } from "../schema/number-constraints.mjs";
|
|
2
2
|
import { ArgSchema } from "../schema/arg.mjs";
|
|
3
|
+
import { StringConstraints } from "../schema/string-constraints.mjs";
|
|
3
4
|
import { FlagSchema } from "../schema/flag.mjs";
|
|
5
|
+
import "../schema/index.mjs";
|
|
4
6
|
//#region src/core/resolve/property.d.ts
|
|
5
7
|
/** Flag/arg kinds that share a common coercion path. */
|
|
6
8
|
declare const SHARED_PROPERTY_MODEL_KINDS: readonly ['string', 'number', 'enum', 'custom'];
|
|
@@ -9,6 +11,7 @@ type SharedPropertyKind = (typeof SHARED_PROPERTY_MODEL_KINDS)[number];
|
|
|
9
11
|
/** Minimal coercion-relevant slice of a flag or arg schema, discriminated by kind. */
|
|
10
12
|
type SharedPropertySchema = {
|
|
11
13
|
readonly kind: 'string';
|
|
14
|
+
readonly stringConstraints: StringConstraints | undefined;
|
|
12
15
|
} | {
|
|
13
16
|
readonly kind: 'number';
|
|
14
17
|
readonly numberConstraints: NumberConstraints | undefined;
|
|
@@ -2,7 +2,10 @@
|
|
|
2
2
|
/** Extract the shared coercion slice from a flag schema, or `undefined` for boolean/array (handled separately). */
|
|
3
3
|
function toSharedFlagPropertySchema(schema) {
|
|
4
4
|
switch (schema.kind) {
|
|
5
|
-
case "string": return {
|
|
5
|
+
case "string": return {
|
|
6
|
+
kind: "string",
|
|
7
|
+
stringConstraints: schema.stringConstraints
|
|
8
|
+
};
|
|
6
9
|
case "number": return {
|
|
7
10
|
kind: "number",
|
|
8
11
|
numberConstraints: schema.numberConstraints
|
|
@@ -16,13 +19,18 @@ function toSharedFlagPropertySchema(schema) {
|
|
|
16
19
|
parseFn: schema.parseFn
|
|
17
20
|
};
|
|
18
21
|
case "boolean":
|
|
19
|
-
case "array":
|
|
22
|
+
case "array":
|
|
23
|
+
case "count":
|
|
24
|
+
case "keyValue": return;
|
|
20
25
|
}
|
|
21
26
|
}
|
|
22
27
|
/** Extract the shared coercion slice from an arg schema (all arg kinds are shared). */
|
|
23
28
|
function toSharedArgPropertySchema(schema) {
|
|
24
29
|
switch (schema.kind) {
|
|
25
|
-
case "string": return {
|
|
30
|
+
case "string": return {
|
|
31
|
+
kind: "string",
|
|
32
|
+
stringConstraints: void 0
|
|
33
|
+
};
|
|
26
34
|
case "number": return {
|
|
27
35
|
kind: "number",
|
|
28
36
|
numberConstraints: schema.numberConstraints
|
|
@@ -87,34 +87,54 @@ interface ProgressHandle {
|
|
|
87
87
|
* without polluting stdout/stderr arrays.
|
|
88
88
|
*/
|
|
89
89
|
type ActivityEvent = {
|
|
90
|
-
/** Spinner created and started. */
|
|
90
|
+
/** Spinner created and started. */
|
|
91
|
+
readonly type: 'spinner:start';
|
|
92
|
+
/** Initial spinner text. */
|
|
91
93
|
readonly text: string;
|
|
92
94
|
} | {
|
|
93
|
-
/** Spinner text changed. */
|
|
95
|
+
/** Spinner text changed. */
|
|
96
|
+
readonly type: 'spinner:update';
|
|
97
|
+
/** Updated spinner text. */
|
|
94
98
|
readonly text: string;
|
|
95
99
|
} | {
|
|
96
|
-
/** Spinner completed successfully. */
|
|
100
|
+
/** Spinner completed successfully. */
|
|
101
|
+
readonly type: 'spinner:succeed';
|
|
102
|
+
/** Success message. */
|
|
97
103
|
readonly text: string;
|
|
98
104
|
} | {
|
|
99
|
-
/** Spinner stopped with an error. */
|
|
105
|
+
/** Spinner stopped with an error. */
|
|
106
|
+
readonly type: 'spinner:fail';
|
|
107
|
+
/** Failure message. */
|
|
100
108
|
readonly text: string;
|
|
101
109
|
} | {
|
|
102
|
-
/** Spinner stopped without a final status. */
|
|
110
|
+
/** Spinner stopped without a final status. */
|
|
111
|
+
readonly type: 'spinner:stop';
|
|
103
112
|
} | {
|
|
104
|
-
/** Progress bar created and started. */
|
|
105
|
-
readonly
|
|
113
|
+
/** Progress bar created and started. */
|
|
114
|
+
readonly type: 'progress:start';
|
|
115
|
+
/** Bar label. */
|
|
116
|
+
readonly label: string;
|
|
117
|
+
/** Known total, or `undefined` for indeterminate. */
|
|
106
118
|
readonly total: number | undefined;
|
|
107
119
|
} | {
|
|
108
|
-
/** Progress bar advanced. */
|
|
120
|
+
/** Progress bar advanced. */
|
|
121
|
+
readonly type: 'progress:increment';
|
|
122
|
+
/** Amount advanced. */
|
|
109
123
|
readonly delta: number;
|
|
110
124
|
} | {
|
|
111
|
-
/** Progress bar set to an absolute value. */
|
|
125
|
+
/** Progress bar set to an absolute value. */
|
|
126
|
+
readonly type: 'progress:update';
|
|
127
|
+
/** New absolute value. */
|
|
112
128
|
readonly value: number;
|
|
113
129
|
} | {
|
|
114
|
-
/** Progress bar completed. */
|
|
130
|
+
/** Progress bar completed. */
|
|
131
|
+
readonly type: 'progress:done';
|
|
132
|
+
/** Completion message, if any. */
|
|
115
133
|
readonly text: string | undefined;
|
|
116
134
|
} | {
|
|
117
|
-
/** Progress bar stopped with an error. */
|
|
135
|
+
/** Progress bar stopped with an error. */
|
|
136
|
+
readonly type: 'progress:fail';
|
|
137
|
+
/** Failure message, if any. */
|
|
118
138
|
readonly text: string | undefined;
|
|
119
139
|
};
|
|
120
140
|
/**
|
|
@@ -1,5 +1,4 @@
|
|
|
1
1
|
import { NumberConstraints } from "./number-constraints.mjs";
|
|
2
|
-
|
|
3
2
|
//#region src/core/schema/arg.d.ts
|
|
4
3
|
/** All arg presence states as a runtime array. */
|
|
5
4
|
declare const ARG_PRESENCES: readonly ['required', 'optional', 'defaulted'];
|
|
@@ -60,7 +59,7 @@ type ResolvedArgValue<C extends ArgConfig> = C['variadic'] extends true ? C['val
|
|
|
60
59
|
/** Extract the resolved value type from an {@linkcode ArgBuilder}. */
|
|
61
60
|
type InferArg<B> = B extends ArgBuilder<infer C extends ArgConfig> ? ResolvedArgValue<C> : never;
|
|
62
61
|
/** Extract resolved value types from a record of builders. */
|
|
63
|
-
type InferArgs<T extends Record<string, ArgBuilder<ArgConfig>>> = { [K in keyof T]: InferArg<T[K]
|
|
62
|
+
type InferArgs<T extends Record<string, ArgBuilder<ArgConfig>>> = { [K in keyof T]: InferArg<T[K]>; };
|
|
64
63
|
/** All arg kind discriminators as a runtime array. */
|
|
65
64
|
declare const ARG_KINDS: readonly ['string', 'number', 'enum', 'custom'];
|
|
66
65
|
/** Discriminator for the kind of value an arg accepts. */
|
|
@@ -5,7 +5,6 @@ import { FlagBuilder, FlagConfig, FlagSchema, InferFlags } from "./flag.mjs";
|
|
|
5
5
|
import { ErasedMiddlewareHandler, Middleware } from "./middleware.mjs";
|
|
6
6
|
import { RunOptions, RunResult } from "./run.mjs";
|
|
7
7
|
import { Colors } from "ansispeck";
|
|
8
|
-
|
|
9
8
|
//#region src/core/schema/command.d.ts
|
|
10
9
|
/**
|
|
11
10
|
* Widen the context type when adding middleware.
|
|
@@ -22,7 +21,7 @@ type WidenContext<C extends Record<string, unknown>, Output extends Record<strin
|
|
|
22
21
|
/**
|
|
23
22
|
* Widen the context type when adding command-scoped derived context.
|
|
24
23
|
*
|
|
25
|
-
* Validation-only derive handlers return `undefined
|
|
24
|
+
* Validation-only derive handlers return `undefined` (or nothing), preserving `C`.
|
|
26
25
|
* Context-producing derive handlers return an object that merges into `C`
|
|
27
26
|
* using the same first-call replacement rules as middleware.
|
|
28
27
|
*/
|
|
@@ -331,12 +330,13 @@ type DeriveParams<F extends Record<string, FlagBuilder<FlagConfig>>, A extends R
|
|
|
331
330
|
*
|
|
332
331
|
* Derive handlers may:
|
|
333
332
|
* - validate resolved input and throw {@linkcode CLIError}
|
|
334
|
-
* - return `undefined` to continue without changing context
|
|
333
|
+
* - return nothing (or `undefined`) to continue without changing context
|
|
335
334
|
* - return an object whose properties merge into `ctx` downstream
|
|
336
335
|
*
|
|
336
|
+
* Handlers may be async; the resolved value follows the same rules.
|
|
337
337
|
* They cannot wrap downstream execution; use {@linkcode middleware} for that.
|
|
338
338
|
*/
|
|
339
|
-
type DeriveHandler<F extends Record<string, FlagBuilder<FlagConfig>>, A extends Record<string, ArgBuilder<ArgConfig>>, C extends Record<string, unknown> = Record<string, never>, Output extends Record<string, unknown> | undefined = undefined> = (params: DeriveParams<F, A, C>) => Output | Promise<Output>;
|
|
339
|
+
type DeriveHandler<F extends Record<string, FlagBuilder<FlagConfig>>, A extends Record<string, ArgBuilder<ArgConfig>>, C extends Record<string, unknown> = Record<string, never>, Output extends Record<string, unknown> | undefined = undefined> = (params: DeriveParams<F, A, C>) => Output | Promise<Output> | void | Promise<void>;
|
|
340
340
|
/**
|
|
341
341
|
* Type-erased derive handler stored on the command builder.
|
|
342
342
|
*
|
|
@@ -598,9 +598,11 @@ declare class CommandBuilder<F extends Record<string, FlagBuilder<FlagConfig>> =
|
|
|
598
598
|
* Derive runs after full resolution and before the action handler.
|
|
599
599
|
* It receives typed `{ args, flags, ctx, out, meta }` and may either:
|
|
600
600
|
*
|
|
601
|
-
* - return `undefined` for validation-only behavior
|
|
601
|
+
* - return nothing (or `undefined`) for validation-only behavior
|
|
602
602
|
* - return an object to merge additional properties into `ctx`
|
|
603
603
|
*
|
|
604
|
+
* Handlers may be async — the runtime awaits them before continuing.
|
|
605
|
+
*
|
|
604
606
|
* Unlike middleware, derive cannot wrap downstream execution and does not
|
|
605
607
|
* use `next()`. Use {@linkcode middleware} for timing, logging, retries, cleanup,
|
|
606
608
|
* or error-boundary patterns.
|
|
@@ -629,7 +631,7 @@ declare class CommandBuilder<F extends Record<string, FlagBuilder<FlagConfig>> =
|
|
|
629
631
|
* @param handler - Derive function receiving typed args/flags/ctx.
|
|
630
632
|
* @returns The builder (for chaining).
|
|
631
633
|
*/
|
|
632
|
-
derive<Output extends Record<string, unknown> | undefined>(handler: DeriveHandler<F, A, C, Output>): CommandBuilder<F, A, WidenDerivedContext<C, Output>>;
|
|
634
|
+
derive<Output extends Record<string, unknown> | undefined = undefined>(handler: DeriveHandler<F, A, C, Output>): CommandBuilder<F, A, WidenDerivedContext<C, Output>>;
|
|
633
635
|
/**
|
|
634
636
|
* Register middleware to run before the action handler.
|
|
635
637
|
*
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { CLIError } from "../errors/index.mjs";
|
|
2
|
+
import { getFlagNegatedName } from "./flag.mjs";
|
|
2
3
|
//#region src/core/schema/command.ts
|
|
3
4
|
/**
|
|
4
5
|
* Validate a new arg entry against invariants before adding it to the command.
|
|
@@ -39,21 +40,32 @@ function formatFlagToken(name, kind) {
|
|
|
39
40
|
}
|
|
40
41
|
function describeFlagForm(form) {
|
|
41
42
|
if (form.kind === "canonical") return `canonical flag ${formatFlagToken(form.name, form.kind)}`;
|
|
43
|
+
if (form.kind === "negation") return `${form.hidden ? "hidden " : ""}negated spelling ${formatFlagToken(form.name, form.kind)}`;
|
|
42
44
|
const aliasType = form.name.length === 1 ? "short alias" : "long alias";
|
|
43
45
|
return `${form.hidden ? "hidden " : ""}${aliasType} ${formatFlagToken(form.name, form.kind)}`;
|
|
44
46
|
}
|
|
45
47
|
function listFlagForms(name, schema) {
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
48
|
+
const negatedName = getFlagNegatedName(name, schema);
|
|
49
|
+
return [
|
|
50
|
+
{
|
|
51
|
+
owner: name,
|
|
52
|
+
name,
|
|
53
|
+
kind: "canonical",
|
|
54
|
+
hidden: false
|
|
55
|
+
},
|
|
56
|
+
...schema.aliases.map((alias) => ({
|
|
57
|
+
owner: name,
|
|
58
|
+
name: alias.name,
|
|
59
|
+
kind: "alias",
|
|
60
|
+
hidden: alias.hidden
|
|
61
|
+
})),
|
|
62
|
+
...negatedName !== void 0 && schema.negation !== void 0 ? [{
|
|
63
|
+
owner: name,
|
|
64
|
+
name: negatedName,
|
|
65
|
+
kind: "negation",
|
|
66
|
+
hidden: schema.negation.hidden
|
|
67
|
+
}] : []
|
|
68
|
+
];
|
|
57
69
|
}
|
|
58
70
|
function throwFlagCollisionError(commandName, form, existing, options) {
|
|
59
71
|
const inherited = options?.inherited ?? false;
|
|
@@ -219,9 +231,11 @@ var CommandBuilder = class CommandBuilder {
|
|
|
219
231
|
* Derive runs after full resolution and before the action handler.
|
|
220
232
|
* It receives typed `{ args, flags, ctx, out, meta }` and may either:
|
|
221
233
|
*
|
|
222
|
-
* - return `undefined` for validation-only behavior
|
|
234
|
+
* - return nothing (or `undefined`) for validation-only behavior
|
|
223
235
|
* - return an object to merge additional properties into `ctx`
|
|
224
236
|
*
|
|
237
|
+
* Handlers may be async — the runtime awaits them before continuing.
|
|
238
|
+
*
|
|
225
239
|
* Unlike middleware, derive cannot wrap downstream execution and does not
|
|
226
240
|
* use `next()`. Use {@linkcode middleware} for timing, logging, retries, cleanup,
|
|
227
241
|
* or error-boundary patterns.
|