@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.
Files changed (88) hide show
  1. package/CHANGELOG.md +49 -1
  2. package/dist/core/cli/dispatch.d.mts +0 -1
  3. package/dist/core/cli/dispatch.mjs +1 -1
  4. package/dist/core/cli/help-links.d.mts +0 -1
  5. package/dist/core/cli/index.d.mts +0 -1
  6. package/dist/core/cli/index.mjs +9 -7
  7. package/dist/core/cli/planner.d.mts +0 -1
  8. package/dist/core/cli/planner.mjs +3 -3
  9. package/dist/core/cli/plugin.d.mts +1 -1
  10. package/dist/core/cli/propagate.d.mts +1 -1
  11. package/dist/core/cli/root-help.d.mts +0 -1
  12. package/dist/core/cli/root-help.mjs +6 -1
  13. package/dist/core/cli/root-surface.d.mts +0 -1
  14. package/dist/core/cli/runtime-preflight.d.mts +5 -1
  15. package/dist/core/cli/runtime-preflight.mjs +2 -1
  16. package/dist/core/completion/index.d.mts +0 -1
  17. package/dist/core/completion/index.mjs +1 -1
  18. package/dist/core/completion/shells/bash.d.mts +0 -1
  19. package/dist/core/completion/shells/bash.mjs +3 -2
  20. package/dist/core/completion/shells/fish.d.mts +0 -1
  21. package/dist/core/completion/shells/fish.mjs +3 -2
  22. package/dist/core/completion/shells/powershell.d.mts +0 -1
  23. package/dist/core/completion/shells/powershell.mjs +2 -1
  24. package/dist/core/completion/shells/shared.d.mts +1 -1
  25. package/dist/core/completion/shells/shared.mjs +5 -0
  26. package/dist/core/completion/shells/zsh.d.mts +0 -1
  27. package/dist/core/completion/shells/zsh.mjs +3 -2
  28. package/dist/core/config/index.d.mts +0 -1
  29. package/dist/core/config/index.mjs +2 -2
  30. package/dist/core/config/package-json.d.mts +0 -1
  31. package/dist/core/execution/index.d.mts +0 -1
  32. package/dist/core/execution/index.mjs +3 -2
  33. package/dist/core/help/ansi.mjs +3 -2
  34. package/dist/core/help/index.d.mts +1 -1
  35. package/dist/core/help/index.mjs +12 -6
  36. package/dist/core/json-schema/index.d.mts +1 -1
  37. package/dist/core/json-schema/index.mjs +25 -7
  38. package/dist/core/output/activity.d.mts +0 -1
  39. package/dist/core/output/contracts.d.mts +0 -1
  40. package/dist/core/output/contracts.mjs +1 -1
  41. package/dist/core/output/index.d.mts +0 -1
  42. package/dist/core/output/index.mjs +1 -1
  43. package/dist/core/output/renderers.d.mts +0 -1
  44. package/dist/core/parse/index.d.mts +1 -1
  45. package/dist/core/parse/index.mjs +75 -9
  46. package/dist/core/prompt/index.d.mts +1 -0
  47. package/dist/core/resolve/args.d.mts +1 -1
  48. package/dist/core/resolve/coerce.d.mts +1 -1
  49. package/dist/core/resolve/coerce.mjs +71 -14
  50. package/dist/core/resolve/contracts.d.mts +6 -1
  51. package/dist/core/resolve/errors.d.mts +0 -1
  52. package/dist/core/resolve/flags.d.mts +7 -2
  53. package/dist/core/resolve/flags.mjs +61 -6
  54. package/dist/core/resolve/index.d.mts +1 -1
  55. package/dist/core/resolve/index.mjs +1 -1
  56. package/dist/core/resolve/property.d.mts +3 -0
  57. package/dist/core/resolve/property.mjs +11 -3
  58. package/dist/core/schema/activity.d.mts +31 -11
  59. package/dist/core/schema/arg.d.mts +1 -2
  60. package/dist/core/schema/command.d.mts +8 -6
  61. package/dist/core/schema/command.mjs +3 -1
  62. package/dist/core/schema/flag.d.mts +337 -10
  63. package/dist/core/schema/flag.mjs +185 -3
  64. package/dist/core/schema/index.d.mts +4 -2
  65. package/dist/core/schema/middleware.d.mts +4 -3
  66. package/dist/core/schema/prompt.d.mts +5 -2
  67. package/dist/core/schema/run.d.mts +9 -1
  68. package/dist/core/schema/string-constraints.d.mts +97 -0
  69. package/dist/core/schema/string-constraints.mjs +69 -0
  70. package/dist/core/schema/value-parsers.d.mts +78 -0
  71. package/dist/core/schema/value-parsers.mjs +142 -0
  72. package/dist/core/schema-dsl/to-json-schema.d.mts +0 -1
  73. package/dist/core/testkit/index.d.mts +0 -31
  74. package/dist/core/testkit/index.mjs +1 -1
  75. package/dist/index.d.mts +5 -2
  76. package/dist/index.mjs +5 -5
  77. package/dist/runtime/adapter.d.mts +22 -1
  78. package/dist/runtime/adapter.mjs +3 -0
  79. package/dist/runtime/auto.d.mts +0 -1
  80. package/dist/runtime/deno.d.mts +15 -5
  81. package/dist/runtime/deno.mjs +9 -0
  82. package/dist/runtime/node.d.mts +2 -2
  83. package/dist/runtime/node.mjs +10 -0
  84. package/dist/runtime.d.mts +1 -0
  85. package/dist/testkit.d.mts +1 -0
  86. package/dist/version.mjs +2 -2
  87. package/dreamcli.schema.json +3 -1
  88. 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) return {
219
- $schema: JSON_SCHEMA_DRAFT,
220
- ...stripCommandDiscriminator(branches[0] ?? {})
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: defaultBranchName !== void 0 ? branches.map((branch) => getBranchCommandDiscriminator(branch) === defaultBranchName ? stripCommandDiscriminator(branch) : branch) : branches
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[];
@@ -1,6 +1,5 @@
1
1
  import { ActivityEvent, ProgressHandle, ProgressOptions, SpinnerHandle } from "../schema/activity.mjs";
2
2
  import { WriteFn } from "./writer.mjs";
3
-
4
3
  //#region src/core/output/activity.d.ts
5
4
  /**
6
5
  * Noop spinner handle singleton.
@@ -1,5 +1,4 @@
1
1
  import { Fallback, TableOptions } from "../schema/activity.mjs";
2
-
3
2
  //#region src/core/output/contracts.d.ts
4
3
  /** Ordered output verbosity levels owned by the output policy layer. */
5
4
  declare const OUTPUT_VERBOSITY_LEVELS: readonly ['normal', 'quiet'];
@@ -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,6 @@
1
1
  import { FlagSchema } from "../schema/flag.mjs";
2
+ import "../schema/index.mjs";
2
3
  import { CommandSchema } from "../schema/command.mjs";
3
-
4
4
  //#region src/core/parse/index.d.ts
5
5
  /**
6
6
  * Token discriminated union.
@@ -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": return raw;
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 flags[canonicalName] = true;
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
- flags[canonicalName] = true;
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
- if (Array.isArray(existing)) existing.push(coerced);
461
- else flags[name] = [coerced];
462
- } else flags[name] = coerced;
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
- ok: true,
138
- value: raw
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 {
@@ -1,5 +1,4 @@
1
1
  import { ValidationError } from "../errors/index.mjs";
2
-
3
2
  //#region src/core/resolve/errors.d.ts
4
3
  /** Type-narrowing guard that asserts a readonly array has at least one element. */
5
4
  declare function isNonEmpty<T>(arr: readonly T[]): arr is readonly [T, ...T[]];
@@ -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
- return new ValidationError(`Prompt kind '${promptKind}' is not compatible with ${flagKind} flag --${flagName}. Use '${allowed[0]}' instead`, {
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: '${allowed[0]}' } for --${flagName}`
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
- sources.push(`Provide --${name}${schema.kind !== "boolean" ? " <value>" : ""}`);
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 { kind: "string" };
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": return;
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 { kind: "string" };
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