@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
package/CHANGELOG.md CHANGED
@@ -7,6 +7,53 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [3.0.0-rc.7] - 2026-07-10
11
+
12
+ ### Added
13
+
14
+ - **`.derive()` handlers may omit the return** — a validation-only derive with
15
+ no `return` statement (sync or async) now typechecks; previously `void` /
16
+ `Promise<void>` failed the `Output` constraint and forced an explicit
17
+ `return undefined`.
18
+ - **String constraints** — `flag.string({ nonEmpty, minLength, maxLength, pattern })`
19
+ plus chained `.nonEmpty()` / `.minLength()` / `.maxLength()` / `.pattern()`,
20
+ mirroring the numeric-constraint model. Checked in fixed order
21
+ (nonEmpty → minLength → maxLength → pattern) at both the CLI parse boundary
22
+ (`INVALID_VALUE`) and env/config/prompt resolution (`CONSTRAINT_VIOLATED`),
23
+ and emitted into the exported JSON Schema as `minLength` / `maxLength` /
24
+ `pattern`.
25
+ - **`.separator()` and `.unique()` on array flags** — `.separator(',')` splits
26
+ each CLI occurrence before element coercion, so `--region us,eu --region ap`
27
+ works alongside repetition and errors name the offending element. Env/config
28
+ string values use the same separator (default remains `','`). `.unique()`
29
+ deduplicates the final resolved array (first-seen order) regardless of
30
+ source.
31
+ - **`flag.url()`** — parses into a `URL`, with optional
32
+ `{ protocols: ['https'] }` allowlist. Help shows `<url>`.
33
+ - **`flag.path()`** — path string with opt-in filesystem checks
34
+ (`{ mustExist: true }`, `{ type: 'file' | 'directory' }`) validated after
35
+ resolution through the runtime adapter, so CLI/env/config values are checked
36
+ identically. `RuntimeAdapter` gained a `stat()` primitive (Node/Bun via
37
+ `node:fs/promises`, Deno via `Deno.stat`; test adapters default to "nothing
38
+ exists"), and `RunOptions` / `ResolveOptions` accept a `stat` injection for
39
+ process-free execution — without one, checks are skipped.
40
+ - **`flag.date()`** — strict ISO-8601 → `Date` with optional inclusive
41
+ `min` / `max` bounds. Rejects lenient `Date.parse` inputs (`'0'`,
42
+ `'March 5'`) and calendar-invalid dates (`2026-02-31`).
43
+ - **`flag.duration()`** — `'30s'`, `'5m'`, `'1.5h'`, `'250ms'`, `'2d'`,
44
+ compounds (`'1h30m'`), or bare milliseconds → milliseconds.
45
+ - **`flag.bytes()`** — `'512mb'`, `'1.5gb'`, `'64kb'` or bare bytes → bytes
46
+ (binary units, case-insensitive).
47
+ - **`flag.count()`** — occurrence counter (`-vvv` → `3`, absent → `0`,
48
+ explicit `--verbose=2` supported). Takes no value token, not promptable,
49
+ and joins boolean flags in help (no `<value>` placeholder) and shell
50
+ completions.
51
+ - **`flag.keyValue()`** — repeated `KEY=VALUE` merges into
52
+ `Record<string, string>` (split at the first `=`, later keys win, unset
53
+ resolves to `{}`). Env accepts comma-separated pairs; config accepts a plain
54
+ object. New `'empty-object'` optional fallback joins arrays' `[]` as the
55
+ kinds that resolve to a value when unset.
56
+
10
57
  ## [3.0.0-rc.6] - 2026-07-09
11
58
 
12
59
  ### Added
@@ -1083,7 +1130,8 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
1083
1130
  - MIT License.
1084
1131
  - Markdownlint configuration.
1085
1132
 
1086
- [Unreleased]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.6...HEAD
1133
+ [Unreleased]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.7...HEAD
1134
+ [3.0.0-rc.7]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.6...v3.0.0-rc.7
1087
1135
  [3.0.0-rc.6]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.5...v3.0.0-rc.6
1088
1136
  [3.0.0-rc.5]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.4...v3.0.0-rc.5
1089
1137
  [3.0.0-rc.4]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.3...v3.0.0-rc.4
@@ -1,6 +1,5 @@
1
1
  import { FlagSchema } from "../schema/flag.mjs";
2
2
  import { CommandSchema, ErasedCommand } from "../schema/command.mjs";
3
-
4
3
  //#region src/core/cli/dispatch.d.ts
5
4
  /**
6
5
  * Flag lookup (name/alias → `[canonicalName, schema]`) used to make the
@@ -211,4 +211,4 @@ function uniqueCommands(commands) {
211
211
  return result;
212
212
  }
213
213
  //#endregion
214
- export { dispatch, findClosestCommand };
214
+ export { consumesFollowingToken, dispatch, findClosestCommand, levenshtein, uniqueCommands };
@@ -1,5 +1,4 @@
1
1
  import { PackageJsonData } from "../config/package-json.mjs";
2
-
3
2
  //#region src/core/cli/help-links.d.ts
4
3
  /**
5
4
  * OSC 8 hyperlink targets for the root-help header.
@@ -10,7 +10,6 @@ import { CompletionOptions } from "../completion/shells/shared.mjs";
10
10
  import { Shell } from "../completion/index.mjs";
11
11
  import { FormatLoader } from "../config/index.mjs";
12
12
  import { formatRootHelp } from "./root-help.mjs";
13
-
14
13
  //#region src/core/cli/index.d.ts
15
14
  /**
16
15
  * Runtime descriptor for the CLI program.
@@ -1,18 +1,18 @@
1
- import { getFlagAliasNames } from "../schema/flag.mjs";
2
1
  import { CLIError } from "../errors/index.mjs";
3
- import { SHELLS, detectShell, generateCompletion, normalizeShell } from "../completion/index.mjs";
4
- import { formatHelp } from "../help/index.mjs";
5
- import { clearRequestedExitCode, createCaptureOutput, createOutput } from "../output/index.mjs";
2
+ import { getFlagAliasNames } from "../schema/flag.mjs";
6
3
  import { arg } from "../schema/arg.mjs";
7
4
  import { command } from "../schema/command.mjs";
8
5
  import { includesBeforeSeparator } from "../parse/index.mjs";
6
+ import { SHELLS, detectShell, generateCompletion, normalizeShell } from "../completion/index.mjs";
7
+ import { formatHelp } from "../help/index.mjs";
8
+ import { clearRequestedExitCode, createCaptureOutput, createOutput } from "../output/index.mjs";
9
9
  import { buildRunResult, executeCommand } from "../execution/index.mjs";
10
10
  import { runCommand } from "../testkit/index.mjs";
11
11
  import { stripTrailing } from "../../strings.mjs";
12
12
  import { createAdapter } from "../../runtime/auto.mjs";
13
13
  import { deriveHelpLinks } from "./help-links.mjs";
14
14
  import { planInvocation } from "./planner.mjs";
15
- import "./plugin.mjs";
15
+ import { plugin } from "./plugin.mjs";
16
16
  import { formatRootHelp } from "./root-help.mjs";
17
17
  import { prepareRuntimePreflight } from "./runtime-preflight.mjs";
18
18
  //#region src/core/cli/index.ts
@@ -119,6 +119,7 @@ function buildCommandRunOptions(options, helpOptions, meta) {
119
119
  ...options?.stdinData !== void 0 ? { stdinData: options.stdinData } : {},
120
120
  ...options?.prompter !== void 0 ? { prompter: options.prompter } : {},
121
121
  ...options?.answers !== void 0 ? { answers: options.answers } : {},
122
+ ...options?.stat !== void 0 ? { stat: options.stat } : {},
122
123
  ...options?.verbosity !== void 0 ? { verbosity: options.verbosity } : {},
123
124
  ...options?.jsonMode !== void 0 ? { jsonMode: options.jsonMode } : {},
124
125
  ...options?.isTTY !== void 0 ? { isTTY: options.isTTY } : {},
@@ -513,8 +514,9 @@ var CLIBuilder = class CLIBuilder {
513
514
  });
514
515
  else out.log(script);
515
516
  });
517
+ const withCompletions = this.command(cmd);
516
518
  return new CLIBuilder({
517
- ...this.command(cmd).schema,
519
+ ...withCompletions.schema,
518
520
  hasBuiltInCompletions: true
519
521
  });
520
522
  }
@@ -923,4 +925,4 @@ function cli(nameOrOptions) {
923
925
  });
924
926
  }
925
927
  //#endregion
926
- export { CLIBuilder, cli };
928
+ export { CLIBuilder, cli, formatRootHelp, plugin };
@@ -5,7 +5,6 @@ import { HelpOptions } from "../help/index.mjs";
5
5
  import { CommandMeta, CommandSchema, ErasedCommand } from "../schema/command.mjs";
6
6
  import { CompletionOptions } from "../completion/shells/shared.mjs";
7
7
  import { Shell } from "../completion/index.mjs";
8
-
9
8
  //#region src/core/cli/planner.d.ts
10
9
  /**
11
10
  * Structural subset of CLISchema used by the planner.
@@ -1,7 +1,7 @@
1
- import { collectPropagatedFlags } from "./propagate.mjs";
2
1
  import { CLIError, ParseError } from "../errors/index.mjs";
3
- import { normalizeShell } from "../completion/index.mjs";
4
2
  import { buildFlagLookup, flagExpectsValue, includesBeforeSeparator } from "../parse/index.mjs";
3
+ import { collectPropagatedFlags } from "./propagate.mjs";
4
+ import { normalizeShell } from "../completion/index.mjs";
5
5
  import { dispatch, findClosestCommand } from "./dispatch.mjs";
6
6
  //#region src/core/cli/planner.ts
7
7
  function buildMeta(schema, helpOptions, commandName) {
@@ -297,4 +297,4 @@ function planInvocation(options) {
297
297
  }
298
298
  }
299
299
  //#endregion
300
- export { planInvocation };
300
+ export { buildCommandExecutionPlan, buildRootCommandMap, mergeCommandSchema, planInvocation };
@@ -1,6 +1,6 @@
1
1
  import { DeprecationWarning } from "../resolve/contracts.mjs";
2
+ import "../resolve/index.mjs";
2
3
  import { CommandMeta, CommandSchema, Out } from "../schema/command.mjs";
3
-
4
4
  //#region src/core/cli/plugin.d.ts
5
5
  /** Shared hook payload for a concrete command execution. */
6
6
  interface PluginCommandContext {
@@ -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/cli/propagate.d.ts
5
5
  /**
6
6
  * Collect propagated flags from a command path.
@@ -1,6 +1,5 @@
1
1
  import { HelpOptions } from "../help/index.mjs";
2
2
  import { CommandSchema } from "../schema/command.mjs";
3
-
4
3
  //#region src/core/cli/root-help.d.ts
5
4
  /** Structural subset of `CLISchema` — avoids circular imports through the barrel. */
6
5
  interface CLISchemaLike {
@@ -1,7 +1,7 @@
1
+ import { command } from "../schema/command.mjs";
1
2
  import { resolveRootSurface } from "./root-surface.mjs";
2
3
  import { osc8, padEnd, wrapText } from "../help/ansi.mjs";
3
4
  import { formatFlagEntriesBlock, formatHelpSections } from "../help/index.mjs";
4
- import { command } from "../schema/command.mjs";
5
5
  //#region src/core/cli/root-help.ts
6
6
  /**
7
7
  * Root-level help formatter for the CLI program.
@@ -105,7 +105,12 @@ function completionsFlagSchema(shells) {
105
105
  description: "Print a shell completion script and exit",
106
106
  enumValues: shells,
107
107
  elementSchema: void 0,
108
+ separator: void 0,
109
+ unique: false,
108
110
  numberConstraints: void 0,
111
+ stringConstraints: void 0,
112
+ pathChecks: void 0,
113
+ valueHint: void 0,
109
114
  prompt: void 0,
110
115
  parseFn: void 0,
111
116
  deprecated: void 0,
@@ -1,5 +1,4 @@
1
1
  import { CommandSchema } from "../schema/command.mjs";
2
-
3
2
  //#region src/core/cli/root-surface.d.ts
4
3
  /**
5
4
  * Structural CLI shape needed for root-surface analysis.
@@ -1,4 +1,5 @@
1
1
  import { Verbosity } from "../output/contracts.mjs";
2
+ import "../output/index.mjs";
2
3
  import { PromptEngine } from "../prompt/index.mjs";
3
4
  import { CLIPlugin } from "./plugin.mjs";
4
5
  import { CLIError } from "../errors/index.mjs";
@@ -9,7 +10,6 @@ import { HelpLinks } from "./help-links.mjs";
9
10
  import { CompletionOptions } from "../completion/shells/shared.mjs";
10
11
  import { Shell } from "../completion/index.mjs";
11
12
  import { FormatLoader } from "../config/index.mjs";
12
-
13
13
  //#region src/core/cli/runtime-preflight.d.ts
14
14
  /** Config discovery settings extracted from CLISchema for preflight use. @internal */
15
15
  interface RuntimeConfigSettings {
@@ -106,6 +106,8 @@ interface RuntimePreflightOptions {
106
106
  readonly jsonMode?: boolean;
107
107
  /** TTY detection override; bypasses adapter TTY check. */
108
108
  readonly isTTY?: boolean;
109
+ /** Filesystem probe override for `flag.path()` checks; bypasses the adapter probe. */
110
+ readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
109
111
  }
110
112
  /**
111
113
  * Fully resolved runtime inputs ready for the execution pipeline.
@@ -129,6 +131,8 @@ interface RuntimeExecutionInputs {
129
131
  readonly prompter?: PromptEngine;
130
132
  /** Loaded config data for the config resolution step. */
131
133
  readonly config?: Readonly<Record<string, unknown>>;
134
+ /** Filesystem probe (from the adapter) for `flag.path()` checks. */
135
+ readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
132
136
  }
133
137
  /** Preflight succeeded — all runtime inputs are resolved and ready for execution. @internal */
134
138
  interface ReadyRuntimePreflight {
@@ -158,6 +158,7 @@ async function prepareRuntimePreflight(options) {
158
158
  isTTY: options.options?.isTTY ?? options.adapter.isTTY,
159
159
  jsonMode,
160
160
  verbosity: options.options?.verbosity ?? "normal",
161
+ stat: options.options?.stat ?? options.adapter.stat,
161
162
  ...stdinData !== void 0 ? { stdinData } : {},
162
163
  ...options.options?.prompter !== void 0 ? { prompter: options.options.prompter } : autoPrompter !== void 0 ? { prompter: autoPrompter } : {},
163
164
  ...loadedConfig !== void 0 ? { config: loadedConfig } : {}
@@ -165,4 +166,4 @@ async function prepareRuntimePreflight(options) {
165
166
  };
166
167
  }
167
168
  //#endregion
168
- export { prepareRuntimePreflight };
169
+ export { commandInvocationNeedsStdin, extractConfigFlag, invocationNeedsStdin, prepareRuntimePreflight };
@@ -4,7 +4,6 @@ import { generateFishCompletion } from "./shells/fish.mjs";
4
4
  import { generatePowerShellCompletion } from "./shells/powershell.mjs";
5
5
  import { generateZshCompletion } from "./shells/zsh.mjs";
6
6
  import { CLISchema } from "../cli/index.mjs";
7
-
8
7
  //#region src/core/completion/index.d.ts
9
8
  /**
10
9
  * Supported shell targets for completion script generation.
@@ -87,4 +87,4 @@ function generateCompletion(schema, shell, options) {
87
87
  }
88
88
  }
89
89
  //#endregion
90
- export { SHELLS, detectShell, generateCompletion, normalizeShell };
90
+ export { SHELLS, detectShell, generateBashCompletion, generateCompletion, generateFishCompletion, generatePowerShellCompletion, generateZshCompletion, normalizeShell };
@@ -1,6 +1,5 @@
1
1
  import { CompletionOptions } from "./shared.mjs";
2
2
  import { CLISchema } from "../../cli/index.mjs";
3
-
4
3
  //#region src/core/completion/shells/bash.d.ts
5
4
  /**
6
5
  * Generate a bash completion script for the CLI.
@@ -1,4 +1,5 @@
1
1
  import { getFlagAliasNames } from "../../schema/flag.mjs";
2
+ import { flagExpectsValue } from "../../parse/index.mjs";
2
3
  import { quoteShellArg, resolveRootCompletionSurface, sanitizeShellIdentifier, versionTag, walkCommandTree } from "./shared.mjs";
3
4
  //#region src/core/completion/shells/bash.ts
4
5
  /**
@@ -254,7 +255,7 @@ function collectFlagWords(flags) {
254
255
  return words.join(" ");
255
256
  }
256
257
  /**
257
- * Collect all non-boolean flag forms across every node and root surface,
258
+ * Collect all value-taking flag forms across every node and root surface,
258
259
  * deduplicated and escaped for use in a bash `case` pattern.
259
260
  *
260
261
  * Returns a `|`-joined pattern like `--schema|-s|--output|-o` that the
@@ -267,7 +268,7 @@ function collectValueFlagPattern(nodes, rootSurface) {
267
268
  const forms = /* @__PURE__ */ new Set();
268
269
  const addFlags = (flags) => {
269
270
  for (const [name, schema] of Object.entries(flags)) {
270
- if (schema.kind === "boolean") continue;
271
+ if (!flagExpectsValue(schema)) continue;
271
272
  forms.add(`--${name}`);
272
273
  for (const alias of getFlagAliasNames(schema, { includeHidden: true })) forms.add(alias.length === 1 ? `-${alias}` : `--${alias}`);
273
274
  }
@@ -1,6 +1,5 @@
1
1
  import { CompletionOptions } from "./shared.mjs";
2
2
  import { CLISchema } from "../../cli/index.mjs";
3
-
4
3
  //#region src/core/completion/shells/fish.d.ts
5
4
  /**
6
5
  * Generate a fish completion script for the CLI.
@@ -1,4 +1,5 @@
1
1
  import { getFlagAliasNames } from "../../schema/flag.mjs";
2
+ import { flagExpectsValue } from "../../parse/index.mjs";
2
3
  import { quoteShellArg, resolveRootCompletionSurface, sanitizeShellIdentifier, versionTag, walkCommandTree } from "./shared.mjs";
3
4
  //#region src/core/completion/shells/fish.ts
4
5
  /**
@@ -111,7 +112,7 @@ function appendFishFlagCompletions(lines, commandName, pathIsFuncName, path, fla
111
112
  parts.push(`-l ${quoteShellArg(name)}`);
112
113
  for (const alias of getFlagAliasNames(schema, { kind: "long" })) parts.push(`-l ${quoteShellArg(alias)}`);
113
114
  parts.push(`-d ${quoteShellArg(schema.description ?? name)}`);
114
- if (schema.kind !== "boolean") parts.push("-r", "-f");
115
+ if (flagExpectsValue(schema)) parts.push("-r", "-f");
115
116
  if (schema.kind === "enum" && schema.enumValues !== void 0) {
116
117
  for (const enumValue of schema.enumValues) lines.push([...parts, `-a ${quoteShellArg(enumValue)}`].join(" "));
117
118
  continue;
@@ -129,7 +130,7 @@ function collectFishValueFlagPatterns(nodes, rootSurface) {
129
130
  ...nodes.map((node) => node.mergedFlags)
130
131
  ];
131
132
  for (const flags of flagSets) for (const [name, schema] of Object.entries(flags)) {
132
- if (schema.kind === "boolean") continue;
133
+ if (!flagExpectsValue(schema)) continue;
133
134
  exact.add(`--${name}`);
134
135
  prefix.add(`--${name}=*`);
135
136
  for (const alias of getFlagAliasNames(schema, {
@@ -1,6 +1,5 @@
1
1
  import { CompletionOptions } from "./shared.mjs";
2
2
  import { CLISchema } from "../../cli/index.mjs";
3
-
4
3
  //#region src/core/completion/shells/powershell.d.ts
5
4
  /**
6
5
  * Generate a PowerShell completion script for the CLI.
@@ -1,4 +1,5 @@
1
1
  import { getFlagAliasNames } from "../../schema/flag.mjs";
2
+ import { flagExpectsValue } from "../../parse/index.mjs";
2
3
  import { resolveRootCompletionSurface, sanitizeShellIdentifier, versionTag, walkCommandTree } from "./shared.mjs";
3
4
  //#region src/core/completion/shells/powershell.ts
4
5
  /**
@@ -109,7 +110,7 @@ function appendPowerShellPathEntry(lines, path, commands, flags) {
109
110
  lines.push(`\t\t\t\tCanonicalName = ${quotePowerShellString(name)}`);
110
111
  lines.push(`\t\t\t\tForms = ${formatPowerShellArray(forms)}`);
111
112
  lines.push(`\t\t\t\tParseForms = ${formatPowerShellArray(parseForms)}`);
112
- lines.push(`\t\t\t\tRequiresValue = ${schema.kind === "boolean" ? "$false" : "$true"}`);
113
+ lines.push(`\t\t\t\tRequiresValue = ${flagExpectsValue(schema) ? "$true" : "$false"}`);
113
114
  lines.push(`\t\t\t\tDescription = ${quotePowerShellString(schema.description ?? name)}`);
114
115
  lines.push(`\t\t\t\tEnumValues = ${formatPowerShellArray(schema.enumValues ?? [])}`);
115
116
  lines.push(" }");
@@ -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/completion/shells/shared.d.ts
5
5
  /**
6
6
  * Format a version tag for generated completion script headers.
@@ -74,7 +74,12 @@ function createSyntheticRootFlag(description) {
74
74
  description,
75
75
  enumValues: void 0,
76
76
  numberConstraints: void 0,
77
+ stringConstraints: void 0,
77
78
  elementSchema: void 0,
79
+ separator: void 0,
80
+ unique: false,
81
+ pathChecks: void 0,
82
+ valueHint: void 0,
78
83
  prompt: void 0,
79
84
  parseFn: void 0,
80
85
  deprecated: void 0,
@@ -1,6 +1,5 @@
1
1
  import { CompletionOptions } from "./shared.mjs";
2
2
  import { CLISchema } from "../../cli/index.mjs";
3
-
4
3
  //#region src/core/completion/shells/zsh.d.ts
5
4
  /**
6
5
  * Generate a zsh completion script for the CLI.
@@ -1,6 +1,7 @@
1
+ import { CLIError } from "../../errors/index.mjs";
1
2
  import { getFlagAliasNames } from "../../schema/flag.mjs";
3
+ import { flagExpectsValue } from "../../parse/index.mjs";
2
4
  import { quoteShellArg, resolveRootCompletionSurface, sanitizeShellIdentifier, versionTag, walkCommandTree } from "./shared.mjs";
3
- import { CLIError } from "../../errors/index.mjs";
4
5
  //#region src/core/completion/shells/zsh.ts
5
6
  /**
6
7
  * Generate a zsh completion script for the CLI.
@@ -217,7 +218,7 @@ function buildZshFlagSpecsFromFlags(flags) {
217
218
  ...longAliases
218
219
  ];
219
220
  let valuePart = "";
220
- if (schema.kind === "boolean") {} else if (schema.kind === "enum" && schema.enumValues !== void 0) valuePart = `:value:(${schema.enumValues.map(escapeZshEnumValue).join(" ")})`;
221
+ if (!flagExpectsValue(schema)) {} else if (schema.kind === "enum" && schema.enumValues !== void 0) valuePart = `:value:(${schema.enumValues.map(escapeZshEnumValue).join(" ")})`;
221
222
  else valuePart = ":value:";
222
223
  if (allForms.length > 1) {
223
224
  const escapedForms = allForms.map(escapeZshCasePatternValue).join(",");
@@ -1,6 +1,5 @@
1
1
  import { RuntimeAdapter } from "../../runtime/adapter.mjs";
2
2
  import { ManifestDiscoveryOptions, PackageJsonAdapter, PackageJsonData, PackageRepository, discoverManifest, discoverPackageJson, inferCliName, packageRepositoryUrl } from "./package-json.mjs";
3
-
4
3
  //#region src/core/config/index.d.ts
5
4
  /**
6
5
  * Format loader — parses file content into a config object.
@@ -1,5 +1,5 @@
1
1
  import { CLIError } from "../errors/index.mjs";
2
- import "./package-json.mjs";
2
+ import { discoverManifest, discoverPackageJson, inferCliName, packageRepositoryUrl } from "./package-json.mjs";
3
3
  //#region src/core/config/index.ts
4
4
  /**
5
5
  * Config file discovery and loading.
@@ -243,4 +243,4 @@ function configFormat(extensions, parse) {
243
243
  };
244
244
  }
245
245
  //#endregion
246
- export { buildConfigSearchPaths, configFormat, discoverConfig };
246
+ export { buildConfigSearchPaths, configFormat, discoverConfig, discoverManifest, discoverPackageJson, inferCliName, packageRepositoryUrl };
@@ -1,5 +1,4 @@
1
1
  import { RuntimeAdapter } from "../../runtime/adapter.mjs";
2
-
3
2
  //#region src/core/config/package-json.d.ts
4
3
  /**
5
4
  * Object form of the package.json `repository` field
@@ -2,7 +2,6 @@ import { CapturedOutput } from "../output/index.mjs";
2
2
  import { CLIError } from "../errors/index.mjs";
3
3
  import { RunOptions, RunResult } from "../schema/run.mjs";
4
4
  import { CommandMeta, CommandSchema, Out, RunnableCommand } from "../schema/command.mjs";
5
-
6
5
  //#region src/core/execution/index.d.ts
7
6
  /**
8
7
  * Explicit executor input for a single command invocation.
@@ -1,7 +1,7 @@
1
1
  import { CLIError } from "../errors/index.mjs";
2
+ import { includesBeforeSeparator, parse } from "../parse/index.mjs";
2
3
  import { formatHelp } from "../help/index.mjs";
3
4
  import { clearRequestedExitCode, getRequestedExitCode } from "../output/index.mjs";
4
- import { includesBeforeSeparator, parse } from "../parse/index.mjs";
5
5
  import { createTestPrompter } from "../prompt/index.mjs";
6
6
  import { resolve } from "../resolve/index.mjs";
7
7
  //#region src/core/execution/index.ts
@@ -48,7 +48,8 @@ async function executeCommand(request) {
48
48
  ...options?.stdinData !== void 0 ? { stdinData: options.stdinData } : {},
49
49
  ...options?.env !== void 0 ? { env: options.env } : {},
50
50
  ...options?.config !== void 0 ? { config: options.config } : {},
51
- ...effectivePrompter !== void 0 ? { prompter: effectivePrompter } : {}
51
+ ...effectivePrompter !== void 0 ? { prompter: effectivePrompter } : {},
52
+ ...options?.stat !== void 0 ? { stat: options.stat } : {}
52
53
  });
53
54
  const resolvedParams = {
54
55
  args: resolved.args,
@@ -67,7 +67,8 @@ const BEL = "\x07";
67
67
  * ```
68
68
  */
69
69
  function osc8(url, text) {
70
- return `${OSC}8;;${url instanceof URL ? url.href : url}${BEL}${text}${OSC}8;;${BEL}`;
70
+ const href = url instanceof URL ? url.href : url;
71
+ return `${OSC}8;;${href}${BEL}${text}${OSC}8;;${BEL}`;
71
72
  }
72
73
  /**
73
74
  * Pad `text` to `length` visible columns with trailing spaces.
@@ -119,4 +120,4 @@ function wrapText(text, width, indent) {
119
120
  return lines.map((line, i) => i === 0 ? line : `${pad}${line}`).join("\n");
120
121
  }
121
122
  //#endregion
122
- export { osc8, padEnd, visibleWidth, wrapText };
123
+ export { osc8, padEnd, stripAnsi, visibleWidth, wrapText };
@@ -1,6 +1,6 @@
1
+ import "../schema/index.mjs";
1
2
  import { osc8, visibleWidth } from "./ansi.mjs";
2
3
  import { CommandSchema } from "../schema/command.mjs";
3
-
4
4
  //#region src/core/help/index.d.ts
5
5
  /** Options for customising help output. */
6
6
  interface HelpOptions {
@@ -1,6 +1,6 @@
1
1
  import { getFlagAliasNames } from "../schema/flag.mjs";
2
2
  import { formatDisplayValue } from "../output/display-value.mjs";
3
- import { padEnd, wrapText } from "./ansi.mjs";
3
+ import { osc8, padEnd, visibleWidth, wrapText } from "./ansi.mjs";
4
4
  //#region src/core/help/index.ts
5
5
  /**
6
6
  * Auto-generated help text from command schemas.
@@ -55,23 +55,29 @@ function formatFlagLeft(name, schema) {
55
55
  `--${name}`,
56
56
  ...visibleLongAliases.map((alias) => `--${alias}`)
57
57
  ];
58
- if (schema.kind !== "boolean") return `${forms.join(", ")} ${formatValueHint(schema)}`;
58
+ if (schema.kind !== "boolean" && schema.kind !== "count") return `${forms.join(", ")} ${formatValueHint(schema)}`;
59
59
  return forms.join(", ");
60
60
  }
61
61
  /**
62
62
  * Produce a type hint like `<string>`, `<number>`, `<us|eu|ap>`.
63
63
  *
64
+ * A schema-level `valueHint` (set by sugar factories like `flag.url()`)
65
+ * overrides the kind-derived hint.
66
+ *
64
67
  * @param schema - The {@link FlagSchema} whose value type determines the hint.
65
- * @returns Angle-bracketed hint string, or empty string for booleans.
68
+ * @returns Angle-bracketed hint string, or empty string for no-value kinds.
66
69
  */
67
70
  function formatValueHint(schema) {
71
+ if (schema.valueHint !== void 0) return `<${schema.valueHint}>`;
68
72
  switch (schema.kind) {
69
73
  case "string": return "<string>";
70
74
  case "number": return "<number>";
71
75
  case "enum": return `<${(schema.enumValues ?? []).join("|")}>`;
72
76
  case "array": return `<${schema.elementSchema !== void 0 ? formatValueHint(schema.elementSchema).slice(1, -1) : "value"}>...`;
73
- case "boolean": return "";
77
+ case "boolean":
78
+ case "count": return "";
74
79
  case "custom": return "<value>";
80
+ case "keyValue": return "<key=value>";
75
81
  }
76
82
  }
77
83
  /**
@@ -88,7 +94,7 @@ function formatFlagDescription(schema) {
88
94
  if (schema.configPath !== void 0) parts.push(`[config: ${schema.configPath}]`);
89
95
  if (schema.prompt !== void 0) parts.push("[prompt]");
90
96
  if (schema.presence === "required") parts.push("[required]");
91
- else if (schema.presence === "defaulted" && schema.kind !== "boolean") parts.push(`(default: ${formatHelpDefaultValue(schema.defaultValue)})`);
97
+ else if (schema.presence === "defaulted" && schema.kind !== "boolean" && schema.kind !== "count") parts.push(`(default: ${formatHelpDefaultValue(schema.defaultValue)})`);
92
98
  return parts.join(" ");
93
99
  }
94
100
  /**
@@ -326,4 +332,4 @@ function formatExamplesSection(examples) {
326
332
  return lines.join("\n");
327
333
  }
328
334
  //#endregion
329
- export { formatFlagEntriesBlock, formatHelp, formatHelpSections };
335
+ export { formatFlagEntriesBlock, formatHelp, formatHelpSections, osc8, visibleWidth };
@@ -1,6 +1,6 @@
1
+ import "../schema/index.mjs";
1
2
  import { CommandSchema } from "../schema/command.mjs";
2
3
  import { CLISchema } from "../cli/index.mjs";
3
-
4
4
  //#region src/core/json-schema/index.d.ts
5
5
  /**
6
6
  * Options for JSON Schema generation.