@kjanat/dreamcli 3.0.0-rc.6 → 3.0.0-rc.7
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 +49 -1
- package/dist/core/cli/dispatch.d.mts +0 -1
- package/dist/core/cli/dispatch.mjs +1 -1
- package/dist/core/cli/help-links.d.mts +0 -1
- package/dist/core/cli/index.d.mts +0 -1
- package/dist/core/cli/index.mjs +9 -7
- package/dist/core/cli/planner.d.mts +0 -1
- package/dist/core/cli/planner.mjs +3 -3
- 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 +6 -1
- package/dist/core/cli/root-surface.d.mts +0 -1
- package/dist/core/cli/runtime-preflight.d.mts +5 -1
- package/dist/core/cli/runtime-preflight.mjs +2 -1
- 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 +3 -2
- package/dist/core/completion/shells/fish.d.mts +0 -1
- package/dist/core/completion/shells/fish.mjs +3 -2
- package/dist/core/completion/shells/powershell.d.mts +0 -1
- package/dist/core/completion/shells/powershell.mjs +2 -1
- package/dist/core/completion/shells/shared.d.mts +1 -1
- package/dist/core/completion/shells/shared.mjs +5 -0
- package/dist/core/completion/shells/zsh.d.mts +0 -1
- package/dist/core/completion/shells/zsh.mjs +3 -2
- package/dist/core/config/index.d.mts +0 -1
- package/dist/core/config/index.mjs +2 -2
- package/dist/core/config/package-json.d.mts +0 -1
- package/dist/core/execution/index.d.mts +0 -1
- package/dist/core/execution/index.mjs +3 -2
- package/dist/core/help/ansi.mjs +3 -2
- package/dist/core/help/index.d.mts +1 -1
- package/dist/core/help/index.mjs +12 -6
- package/dist/core/json-schema/index.d.mts +1 -1
- package/dist/core/json-schema/index.mjs +25 -7
- 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 +1 -1
- package/dist/core/parse/index.mjs +75 -9
- 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 +6 -1
- 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 +1 -1
- 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 +3 -1
- package/dist/core/schema/flag.d.mts +337 -10
- package/dist/core/schema/flag.mjs +185 -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 +9 -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 +5 -2
- package/dist/index.mjs +5 -5
- 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 +3 -1
- package/package.json +12 -13
|
@@ -215,15 +215,19 @@ function generateInputSchema(schema, options) {
|
|
|
215
215
|
if (!opts.includeHidden && cmd.schema.hidden) continue;
|
|
216
216
|
collectInputBranches(cmd.schema, "", branches, opts);
|
|
217
217
|
}
|
|
218
|
-
if (branches.length === 1)
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
218
|
+
if (branches.length === 1) {
|
|
219
|
+
const branch = stripCommandDiscriminator(branches[0] ?? {});
|
|
220
|
+
return {
|
|
221
|
+
$schema: JSON_SCHEMA_DRAFT,
|
|
222
|
+
...branch
|
|
223
|
+
};
|
|
224
|
+
}
|
|
222
225
|
if (branches.length > 0) {
|
|
223
226
|
const defaultBranchName = schema.defaultCommand !== void 0 && (opts.includeHidden || !schema.defaultCommand.schema.hidden) ? schema.defaultCommand.schema.name : void 0;
|
|
227
|
+
const normalizedBranches = defaultBranchName !== void 0 ? branches.map((branch) => getBranchCommandDiscriminator(branch) === defaultBranchName ? stripCommandDiscriminator(branch) : branch) : branches;
|
|
224
228
|
return {
|
|
225
229
|
$schema: JSON_SCHEMA_DRAFT,
|
|
226
|
-
oneOf:
|
|
230
|
+
oneOf: normalizedBranches
|
|
227
231
|
};
|
|
228
232
|
}
|
|
229
233
|
return {
|
|
@@ -302,9 +306,15 @@ function getBranchCommandDiscriminator(branch) {
|
|
|
302
306
|
function flagToJsonSchemaType(schema) {
|
|
303
307
|
const result = {};
|
|
304
308
|
switch (schema.kind) {
|
|
305
|
-
case "string":
|
|
309
|
+
case "string": {
|
|
306
310
|
result.type = "string";
|
|
311
|
+
const constraints = schema.stringConstraints;
|
|
312
|
+
const minLength = constraints?.nonEmpty === true ? Math.max(constraints.minLength ?? 1, 1) : constraints?.minLength;
|
|
313
|
+
if (minLength !== void 0) result.minLength = minLength;
|
|
314
|
+
if (constraints?.maxLength !== void 0) result.maxLength = constraints.maxLength;
|
|
315
|
+
if (constraints?.pattern !== void 0) result.pattern = constraints.pattern.source;
|
|
307
316
|
break;
|
|
317
|
+
}
|
|
308
318
|
case "number": {
|
|
309
319
|
const constraints = schema.numberConstraints;
|
|
310
320
|
result.type = constraints?.int === true ? "integer" : "number";
|
|
@@ -324,6 +334,14 @@ function flagToJsonSchemaType(schema) {
|
|
|
324
334
|
if (schema.elementSchema !== void 0) result.items = flagToJsonSchemaType(schema.elementSchema);
|
|
325
335
|
break;
|
|
326
336
|
case "custom": break;
|
|
337
|
+
case "count":
|
|
338
|
+
result.type = "integer";
|
|
339
|
+
result.minimum = 0;
|
|
340
|
+
break;
|
|
341
|
+
case "keyValue":
|
|
342
|
+
result.type = "object";
|
|
343
|
+
result.additionalProperties = { type: "string" };
|
|
344
|
+
break;
|
|
327
345
|
}
|
|
328
346
|
if (schema.description !== void 0) result.description = schema.description;
|
|
329
347
|
if (schema.presence === "defaulted" && isJsonSerializable(schema.defaultValue)) result.default = schema.defaultValue;
|
|
@@ -485,7 +503,7 @@ const definitionMetaSchema = withDefinitionMetaSchemaDescriptions({
|
|
|
485
503
|
commands: @command[]
|
|
486
504
|
}`),
|
|
487
505
|
flag: def(`{
|
|
488
|
-
kind: 'string' | 'number' | 'boolean' | 'enum' | 'array' | 'custom';
|
|
506
|
+
kind: 'string' | 'number' | 'boolean' | 'enum' | 'array' | 'custom' | 'count' | 'keyValue';
|
|
489
507
|
presence: 'optional' | 'required' | 'defaulted';
|
|
490
508
|
defaultValue?: unknown;
|
|
491
509
|
aliases?: string[];
|
|
@@ -54,4 +54,4 @@ function resolveProgressPolicy(policy, fallback) {
|
|
|
54
54
|
};
|
|
55
55
|
}
|
|
56
56
|
//#endregion
|
|
57
|
-
export { resolveOutputPolicy, resolveProgressPolicy, resolveSpinnerPolicy, resolveTableFormat, resolveTableTextStream, resolveTextStream, shouldEmitInfo };
|
|
57
|
+
export { resolveActivityRenderMode, resolveOutputPolicy, resolveProgressPolicy, resolveSpinnerPolicy, resolveTableFormat, resolveTableTextStream, resolveTextStream, shouldEmitInfo };
|
|
@@ -4,7 +4,6 @@ import { CaptureProgressHandle, CaptureSpinnerHandle, StaticProgressHandle, Stat
|
|
|
4
4
|
import { OutputPolicy, Verbosity } from "./contracts.mjs";
|
|
5
5
|
import { Out } from "../schema/command.mjs";
|
|
6
6
|
import { Colors } from "ansispeck";
|
|
7
|
-
|
|
8
7
|
//#region src/core/output/index.d.ts
|
|
9
8
|
/**
|
|
10
9
|
* Configuration for creating an output channel.
|
|
@@ -439,4 +439,4 @@ function createCaptureOutput(options) {
|
|
|
439
439
|
}), captured.activity), captured];
|
|
440
440
|
}
|
|
441
441
|
//#endregion
|
|
442
|
-
export { clearRequestedExitCode, createCaptureOutput, createOutput, getRequestedExitCode };
|
|
442
|
+
export { CaptureOutputChannel, CaptureProgressHandle, CaptureSpinnerHandle, OutputChannel, clearRequestedExitCode, createCaptureOutput, createOutput, getRequestedExitCode, setRequestedExitCode, writeLine };
|
|
@@ -1,7 +1,6 @@
|
|
|
1
1
|
import { ProgressHandle, ProgressOptions, SpinnerHandle } from "../schema/activity.mjs";
|
|
2
2
|
import { WriteFn } from "./writer.mjs";
|
|
3
3
|
import { ActivityPolicy, OutputStream } from "./contracts.mjs";
|
|
4
|
-
|
|
5
4
|
//#region src/core/output/renderers.d.ts
|
|
6
5
|
/**
|
|
7
6
|
* Paired write functions for the two standard output streams.
|
|
@@ -1,6 +1,7 @@
|
|
|
1
|
+
import { ParseError } from "../errors/index.mjs";
|
|
1
2
|
import { describeNumberConstraintViolation, validateNumberConstraints } from "../schema/number-constraints.mjs";
|
|
3
|
+
import { describeStringConstraintViolation, validateStringConstraints } from "../schema/string-constraints.mjs";
|
|
2
4
|
import { getFlagAliasNames } from "../schema/flag.mjs";
|
|
3
|
-
import { ParseError } from "../errors/index.mjs";
|
|
4
5
|
//#region src/core/parse/index.ts
|
|
5
6
|
/**
|
|
6
7
|
* Argv tokenization and parsing against command schemas.
|
|
@@ -145,7 +146,7 @@ function buildFlagLookup(flags) {
|
|
|
145
146
|
* @returns `true` if the flag expects a value token after it
|
|
146
147
|
*/
|
|
147
148
|
function flagExpectsValue(schema) {
|
|
148
|
-
return schema.kind !== "boolean";
|
|
149
|
+
return schema.kind !== "boolean" && schema.kind !== "count";
|
|
149
150
|
}
|
|
150
151
|
/**
|
|
151
152
|
* Coerce a raw string to the flag's declared kind.
|
|
@@ -158,7 +159,22 @@ function flagExpectsValue(schema) {
|
|
|
158
159
|
*/
|
|
159
160
|
function coerceFlagValue(flagName, raw, schema, displayName = `--${flagName}`) {
|
|
160
161
|
switch (schema.kind) {
|
|
161
|
-
case "string":
|
|
162
|
+
case "string": {
|
|
163
|
+
const violation = validateStringConstraints(raw, schema.stringConstraints);
|
|
164
|
+
if (violation !== void 0) throw new ParseError(`Invalid value '${raw}' for flag ${displayName}: ${describeStringConstraintViolation(violation)}`, {
|
|
165
|
+
code: "INVALID_VALUE",
|
|
166
|
+
details: {
|
|
167
|
+
flag: flagName,
|
|
168
|
+
input: displayName,
|
|
169
|
+
value: raw,
|
|
170
|
+
expected: "string",
|
|
171
|
+
constraint: violation.kind,
|
|
172
|
+
..."bound" in violation ? { bound: violation.bound } : {},
|
|
173
|
+
..."pattern" in violation ? { pattern: violation.pattern } : {}
|
|
174
|
+
}
|
|
175
|
+
});
|
|
176
|
+
return raw;
|
|
177
|
+
}
|
|
162
178
|
case "number": {
|
|
163
179
|
const n = Number(raw);
|
|
164
180
|
if (Number.isNaN(n)) throw new ParseError(`Invalid number value '${raw}' for flag ${displayName}`, {
|
|
@@ -236,6 +252,20 @@ function coerceFlagValue(flagName, raw, schema, displayName = `--${flagName}`) {
|
|
|
236
252
|
cause: err
|
|
237
253
|
});
|
|
238
254
|
}
|
|
255
|
+
case "count": {
|
|
256
|
+
const n = raw.trim() === "" ? NaN : Number(raw);
|
|
257
|
+
if (!Number.isInteger(n) || n < 0) throw new ParseError(`Invalid count value '${raw}' for flag ${displayName}. Use a non-negative integer`, {
|
|
258
|
+
code: "INVALID_VALUE",
|
|
259
|
+
details: {
|
|
260
|
+
flag: flagName,
|
|
261
|
+
input: displayName,
|
|
262
|
+
value: raw,
|
|
263
|
+
expected: "count"
|
|
264
|
+
}
|
|
265
|
+
});
|
|
266
|
+
return n;
|
|
267
|
+
}
|
|
268
|
+
case "keyValue": return parseKeyValuePair(flagName, raw, displayName);
|
|
239
269
|
}
|
|
240
270
|
}
|
|
241
271
|
/**
|
|
@@ -383,7 +413,10 @@ function parseLongFlag(token, tokens, startIdx, flagLookup, flags) {
|
|
|
383
413
|
const [canonicalName, flagSchema] = entry;
|
|
384
414
|
if (!flagExpectsValue(flagSchema)) {
|
|
385
415
|
if (token.value !== void 0) flags[canonicalName] = coerceFlagValue(canonicalName, token.value, flagSchema, `--${token.name}`);
|
|
386
|
-
else
|
|
416
|
+
else if (flagSchema.kind === "count") {
|
|
417
|
+
const existing = flags[canonicalName];
|
|
418
|
+
flags[canonicalName] = (typeof existing === "number" ? existing : 0) + 1;
|
|
419
|
+
} else flags[canonicalName] = true;
|
|
387
420
|
return startIdx + 1;
|
|
388
421
|
}
|
|
389
422
|
if (token.value !== void 0) {
|
|
@@ -424,7 +457,10 @@ function parseShortFlags(token, tokens, startIdx, flagLookup, flags) {
|
|
|
424
457
|
});
|
|
425
458
|
const [canonicalName, flagSchema] = entry;
|
|
426
459
|
if (!flagExpectsValue(flagSchema)) {
|
|
427
|
-
|
|
460
|
+
if (flagSchema.kind === "count") {
|
|
461
|
+
const existing = flags[canonicalName];
|
|
462
|
+
flags[canonicalName] = (typeof existing === "number" ? existing : 0) + 1;
|
|
463
|
+
} else flags[canonicalName] = true;
|
|
428
464
|
continue;
|
|
429
465
|
}
|
|
430
466
|
if (ci < chars.length - 1) {
|
|
@@ -454,12 +490,42 @@ function parseShortFlags(token, tokens, startIdx, flagLookup, flags) {
|
|
|
454
490
|
* @param rawValue - Raw string value from argv
|
|
455
491
|
*/
|
|
456
492
|
function setFlagValue(flags, name, schema, rawValue, displayName = `--${name}`) {
|
|
457
|
-
const coerced = coerceFlagValue(name, rawValue, schema, displayName);
|
|
458
493
|
if (schema.kind === "array") {
|
|
494
|
+
const coercedParts = (schema.separator !== void 0 ? rawValue.split(schema.separator) : [rawValue]).filter((part) => schema.separator === void 0 || part.length > 0).map((part) => coerceFlagValue(name, part, schema, displayName));
|
|
495
|
+
const existing = flags[name];
|
|
496
|
+
if (Array.isArray(existing)) existing.push(...coercedParts);
|
|
497
|
+
else flags[name] = coercedParts;
|
|
498
|
+
return;
|
|
499
|
+
}
|
|
500
|
+
if (schema.kind === "keyValue") {
|
|
501
|
+
const pair = parseKeyValuePair(name, rawValue, displayName);
|
|
459
502
|
const existing = flags[name];
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
}
|
|
503
|
+
flags[name] = Object.fromEntries([...isPlainRecord(existing) ? Object.entries(existing) : [], pair]);
|
|
504
|
+
return;
|
|
505
|
+
}
|
|
506
|
+
flags[name] = coerceFlagValue(name, rawValue, schema, displayName);
|
|
507
|
+
}
|
|
508
|
+
/** Narrow to a mutable string-record accumulator (keyValue flags only ever store these). */
|
|
509
|
+
function isPlainRecord(value) {
|
|
510
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
511
|
+
}
|
|
512
|
+
/**
|
|
513
|
+
* Split a `KEY=VALUE` token at the first `=`.
|
|
514
|
+
*
|
|
515
|
+
* @throws ParseError when the token has no `=` or an empty key.
|
|
516
|
+
*/
|
|
517
|
+
function parseKeyValuePair(flagName, raw, displayName = `--${flagName}`) {
|
|
518
|
+
const eq = raw.indexOf("=");
|
|
519
|
+
if (eq <= 0) throw new ParseError(`Invalid value '${raw}' for flag ${displayName}. Use KEY=VALUE`, {
|
|
520
|
+
code: "INVALID_VALUE",
|
|
521
|
+
details: {
|
|
522
|
+
flag: flagName,
|
|
523
|
+
input: displayName,
|
|
524
|
+
value: raw,
|
|
525
|
+
expected: "key=value"
|
|
526
|
+
}
|
|
527
|
+
});
|
|
528
|
+
return [raw.slice(0, eq), raw.slice(eq + 1)];
|
|
463
529
|
}
|
|
464
530
|
/**
|
|
465
531
|
* Map positional values to named args based on schema ordering.
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { ConfirmPromptConfig, InputPromptConfig, PromptConfig, PromptResult, SelectChoice } from "../schema/prompt.mjs";
|
|
2
2
|
import { WriteFn } from "../output/writer.mjs";
|
|
3
|
+
import "../output/index.mjs";
|
|
3
4
|
//#region src/core/prompt/index.d.ts
|
|
4
5
|
/**
|
|
5
6
|
* A select prompt config with choices guaranteed non-empty.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
+
import "../schema/index.mjs";
|
|
1
2
|
import { DeprecationWarning } from "./contracts.mjs";
|
|
2
3
|
import { CommandArgEntry } from "../schema/command.mjs";
|
|
3
|
-
|
|
4
4
|
//#region src/core/resolve/args.d.ts
|
|
5
5
|
/** Walk every declared arg through the resolution chain (cli -> stdin -> env -> default), collecting deprecations and throwing aggregated errors. */
|
|
6
6
|
declare function resolveArgs(argEntries: readonly CommandArgEntry[], parsedArgs: Readonly<Record<string, unknown>>, stdinData: string | null | undefined, env: Readonly<Record<string, string | undefined>>, deprecations: DeprecationWarning[]): Readonly<Record<string, unknown>>;
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
import { ArgSchema } from "../schema/arg.mjs";
|
|
2
2
|
import { FlagSchema } from "../schema/flag.mjs";
|
|
3
|
+
import "../schema/index.mjs";
|
|
3
4
|
import { ArgDiagnosticSource, FlagDiagnosticSource } from "./contracts.mjs";
|
|
4
5
|
import { ValidationError } from "../errors/index.mjs";
|
|
5
|
-
|
|
6
6
|
//#region src/core/resolve/coerce.d.ts
|
|
7
7
|
type CoerceSource = FlagDiagnosticSource;
|
|
8
8
|
/** Discriminated result of a value coercion attempt — success with the coerced value, or failure with a structured validation error. */
|
|
@@ -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 "../schema/index.mjs";
|
|
1
2
|
import { ParseResult } from "../parse/index.mjs";
|
|
2
3
|
import { PromptEngine } from "../prompt/index.mjs";
|
|
3
4
|
import { CommandSchema } from "../schema/command.mjs";
|
|
4
|
-
|
|
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 "../schema/index.mjs";
|
|
1
2
|
import { ParseResult } from "../parse/index.mjs";
|
|
2
3
|
import { DeprecationWarning, ResolveOptions, ResolveResult } from "./contracts.mjs";
|
|
3
4
|
import { CommandSchema } from "../schema/command.mjs";
|
|
4
|
-
|
|
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
|