@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.
Files changed (94) hide show
  1. package/CHANGELOG.md +94 -1
  2. package/dist/core/cli/dispatch.d.mts +6 -5
  3. package/dist/core/cli/dispatch.mjs +7 -5
  4. package/dist/core/cli/help-links.d.mts +0 -1
  5. package/dist/core/cli/index.d.mts +27 -2
  6. package/dist/core/cli/index.mjs +28 -14
  7. package/dist/core/cli/planner.d.mts +3 -1
  8. package/dist/core/cli/planner.mjs +12 -12
  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 +38 -21
  13. package/dist/core/cli/root-surface.d.mts +0 -1
  14. package/dist/core/cli/runtime-preflight.d.mts +12 -2
  15. package/dist/core/cli/runtime-preflight.mjs +5 -4
  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 +8 -4
  20. package/dist/core/completion/shells/fish.d.mts +0 -1
  21. package/dist/core/completion/shells/fish.mjs +6 -3
  22. package/dist/core/completion/shells/powershell.d.mts +0 -1
  23. package/dist/core/completion/shells/powershell.mjs +10 -5
  24. package/dist/core/completion/shells/shared.d.mts +13 -2
  25. package/dist/core/completion/shells/shared.mjs +24 -2
  26. package/dist/core/completion/shells/zsh.d.mts +0 -1
  27. package/dist/core/completion/shells/zsh.mjs +11 -4
  28. package/dist/core/config/index.d.mts +2 -3
  29. package/dist/core/config/index.mjs +2 -2
  30. package/dist/core/config/package-json.d.mts +27 -4
  31. package/dist/core/config/package-json.mjs +20 -19
  32. package/dist/core/errors/index.d.mts +1 -1
  33. package/dist/core/execution/index.d.mts +0 -1
  34. package/dist/core/execution/index.mjs +8 -4
  35. package/dist/core/help/ansi.mjs +3 -2
  36. package/dist/core/help/index.d.mts +22 -3
  37. package/dist/core/help/index.mjs +65 -53
  38. package/dist/core/help/theme.d.mts +68 -0
  39. package/dist/core/help/theme.mjs +46 -0
  40. package/dist/core/json-schema/index.d.mts +1 -1
  41. package/dist/core/json-schema/index.mjs +39 -8
  42. package/dist/core/json-schema/meta-descriptions.generated.d.mts +22 -5
  43. package/dist/core/json-schema/meta-descriptions.generated.mjs +14 -5
  44. package/dist/core/output/activity.d.mts +0 -1
  45. package/dist/core/output/contracts.d.mts +0 -1
  46. package/dist/core/output/contracts.mjs +1 -1
  47. package/dist/core/output/index.d.mts +0 -1
  48. package/dist/core/output/index.mjs +1 -1
  49. package/dist/core/output/renderers.d.mts +0 -1
  50. package/dist/core/parse/index.d.mts +40 -7
  51. package/dist/core/parse/index.mjs +209 -40
  52. package/dist/core/prompt/index.d.mts +1 -0
  53. package/dist/core/resolve/args.d.mts +1 -1
  54. package/dist/core/resolve/coerce.d.mts +1 -1
  55. package/dist/core/resolve/coerce.mjs +71 -14
  56. package/dist/core/resolve/contracts.d.mts +7 -2
  57. package/dist/core/resolve/errors.d.mts +0 -1
  58. package/dist/core/resolve/flags.d.mts +7 -2
  59. package/dist/core/resolve/flags.mjs +61 -6
  60. package/dist/core/resolve/index.d.mts +2 -2
  61. package/dist/core/resolve/index.mjs +1 -1
  62. package/dist/core/resolve/property.d.mts +3 -0
  63. package/dist/core/resolve/property.mjs +11 -3
  64. package/dist/core/schema/activity.d.mts +31 -11
  65. package/dist/core/schema/arg.d.mts +1 -2
  66. package/dist/core/schema/command.d.mts +8 -6
  67. package/dist/core/schema/command.mjs +26 -12
  68. package/dist/core/schema/flag.d.mts +439 -10
  69. package/dist/core/schema/flag.mjs +255 -3
  70. package/dist/core/schema/index.d.mts +4 -2
  71. package/dist/core/schema/middleware.d.mts +4 -3
  72. package/dist/core/schema/prompt.d.mts +5 -2
  73. package/dist/core/schema/run.d.mts +20 -1
  74. package/dist/core/schema/string-constraints.d.mts +97 -0
  75. package/dist/core/schema/string-constraints.mjs +69 -0
  76. package/dist/core/schema/value-parsers.d.mts +78 -0
  77. package/dist/core/schema/value-parsers.mjs +142 -0
  78. package/dist/core/schema-dsl/to-json-schema.d.mts +0 -1
  79. package/dist/core/testkit/index.d.mts +0 -31
  80. package/dist/core/testkit/index.mjs +1 -1
  81. package/dist/index.d.mts +8 -4
  82. package/dist/index.mjs +7 -7
  83. package/dist/runtime/adapter.d.mts +22 -1
  84. package/dist/runtime/adapter.mjs +3 -0
  85. package/dist/runtime/auto.d.mts +0 -1
  86. package/dist/runtime/deno.d.mts +15 -5
  87. package/dist/runtime/deno.mjs +9 -0
  88. package/dist/runtime/node.d.mts +2 -2
  89. package/dist/runtime/node.mjs +10 -0
  90. package/dist/runtime.d.mts +1 -0
  91. package/dist/testkit.d.mts +1 -0
  92. package/dist/version.mjs +2 -2
  93. package/dreamcli.schema.json +35 -6
  94. 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
- 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 { 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 {
@@ -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 { 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 { 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
@@ -87,34 +87,54 @@ interface ProgressHandle {
87
87
  * without polluting stdout/stderr arrays.
88
88
  */
89
89
  type ActivityEvent = {
90
- /** Spinner created and started. */readonly type: 'spinner:start'; /** Initial spinner text. */
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. */readonly type: 'spinner:update'; /** Updated spinner text. */
95
+ /** Spinner text changed. */
96
+ readonly type: 'spinner:update';
97
+ /** Updated spinner text. */
94
98
  readonly text: string;
95
99
  } | {
96
- /** Spinner completed successfully. */readonly type: 'spinner:succeed'; /** Success message. */
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. */readonly type: 'spinner:fail'; /** Failure message. */
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. */readonly type: 'spinner:stop';
110
+ /** Spinner stopped without a final status. */
111
+ readonly type: 'spinner:stop';
103
112
  } | {
104
- /** Progress bar created and started. */readonly type: 'progress:start'; /** Bar label. */
105
- readonly label: string; /** Known total, or `undefined` for indeterminate. */
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. */readonly type: 'progress:increment'; /** Amount 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. */readonly type: 'progress:update'; /** New 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. */readonly type: 'progress:done'; /** Completion message, if any. */
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. */readonly type: 'progress:fail'; /** Failure message, if any. */
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`, preserving `C`.
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
- return [{
47
- owner: name,
48
- name,
49
- kind: "canonical",
50
- hidden: false
51
- }, ...schema.aliases.map((alias) => ({
52
- owner: name,
53
- name: alias.name,
54
- kind: "alias",
55
- hidden: alias.hidden
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.