@kjanat/dreamcli 2.5.0 → 3.0.0-rc.1

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 (89) hide show
  1. package/CHANGELOG.md +128 -1
  2. package/README.md +9 -2
  3. package/dist/core/cli/index.d.mts +109 -16
  4. package/dist/core/cli/index.mjs +1 -1
  5. package/dist/core/cli/planner.d.mts +27 -5
  6. package/dist/core/cli/planner.mjs +1 -1
  7. package/dist/core/cli/root-help.d.mts +16 -2
  8. package/dist/core/cli/root-help.mjs +3 -5
  9. package/dist/core/cli/root-surface.d.mts +18 -3
  10. package/dist/core/cli/root-surface.mjs +1 -1
  11. package/dist/core/cli/runtime-preflight.d.mts +16 -1
  12. package/dist/core/cli/runtime-preflight.mjs +1 -1
  13. package/dist/core/completion/index.d.mts +32 -1
  14. package/dist/core/completion/index.mjs +1 -1
  15. package/dist/core/completion/shells/shared.d.mts +10 -0
  16. package/dist/core/completion/shells/shared.mjs +1 -1
  17. package/dist/core/help/index.d.mts +45 -1
  18. package/dist/core/help/index.mjs +6 -6
  19. package/dist/core/json-schema/index.mjs +1 -1
  20. package/dist/core/json-schema/meta-descriptions.generated.d.mts +38 -38
  21. package/dist/core/parse/index.d.mts +15 -1
  22. package/dist/core/parse/index.mjs +1 -1
  23. package/dist/core/prompt/index.d.mts +11 -3
  24. package/dist/core/prompt/index.mjs +3 -3
  25. package/dist/core/resolve/coerce.mjs +1 -1
  26. package/dist/core/resolve/flags.mjs +1 -1
  27. package/dist/core/resolve/property.d.mts +2 -0
  28. package/dist/core/resolve/property.mjs +1 -1
  29. package/dist/core/schema/arg.d.mts +90 -10
  30. package/dist/core/schema/arg.mjs +1 -1
  31. package/dist/core/schema/command.d.mts +3 -1
  32. package/dist/core/schema/flag.d.mts +92 -2
  33. package/dist/core/schema/flag.mjs +1 -1
  34. package/dist/core/schema/index.d.mts +2 -1
  35. package/dist/core/schema/number-constraints.d.mts +96 -0
  36. package/dist/core/schema/number-constraints.mjs +1 -0
  37. package/dist/core/schema/prompt.d.mts +15 -0
  38. package/dist/core/schema/run.d.mts +4 -4
  39. package/dist/core/testkit/index.d.mts +9 -5
  40. package/dist/core/testkit/index.mjs +1 -1
  41. package/dist/index.d.mts +2 -1
  42. package/dist/index.mjs +1 -1
  43. package/dist/runtime/auto.mjs +1 -1
  44. package/dist/runtime/bun.mjs +1 -1
  45. package/dist/runtime/deno.mjs +2 -2
  46. package/dist/runtime/node.mjs +2 -2
  47. package/dist/version.mjs +1 -1
  48. package/examples/basic.ts +5 -1
  49. package/examples/gh/package.json +2 -7
  50. package/examples/pwsh-demo/package.json +1 -7
  51. package/examples/pwsh-demo/src/main.test.ts +1 -4
  52. package/examples/pwsh-demo/src/main.ts +14 -4
  53. package/examples/transport-launcher.ts +85 -0
  54. package/package.json +15 -24
  55. package/src/core/cli/dispatch.ts +7 -1
  56. package/src/core/cli/index.ts +235 -34
  57. package/src/core/cli/planner.ts +192 -23
  58. package/src/core/cli/root-help.ts +195 -105
  59. package/src/core/cli/root-surface.ts +25 -12
  60. package/src/core/cli/runtime-preflight.ts +20 -2
  61. package/src/core/completion/index.ts +50 -0
  62. package/src/core/completion/shells/powershell.ts +2 -2
  63. package/src/core/completion/shells/shared.ts +30 -3
  64. package/src/core/execution/index.ts +1 -4
  65. package/src/core/help/index.ts +57 -10
  66. package/src/core/json-schema/index.ts +23 -4
  67. package/src/core/json-schema/meta-descriptions.generated.ts +115 -98
  68. package/src/core/parse/index.ts +62 -1
  69. package/src/core/prompt/index.ts +54 -14
  70. package/src/core/resolve/coerce.ts +73 -5
  71. package/src/core/resolve/flags.ts +14 -0
  72. package/src/core/resolve/property.ts +4 -4
  73. package/src/core/schema/arg.ts +125 -3
  74. package/src/core/schema/command.ts +3 -1
  75. package/src/core/schema/flag.ts +120 -4
  76. package/src/core/schema/index.ts +5 -0
  77. package/src/core/schema/number-constraints.ts +153 -0
  78. package/src/core/schema/prompt.ts +15 -0
  79. package/src/core/schema/run.ts +4 -4
  80. package/src/core/testkit/index.ts +32 -8
  81. package/src/index.ts +2 -0
  82. package/src/runtime/auto.ts +0 -24
  83. package/src/runtime/bun.ts +0 -7
  84. package/src/runtime/deno.ts +0 -2
  85. package/src/runtime/node.ts +0 -11
  86. package/src/runtime/support.ts +1 -59
  87. package/src/schema.ts +16 -0
  88. package/dist/runtime/support.d.mts +0 -42
  89. package/dist/runtime/support.mjs +0 -1
@@ -1 +1 @@
1
- import{CLIError as e,ParseError as t}from"../errors/index.mjs";import{parse as n}from"../parse/index.mjs";import{createTerminalPrompter as r}from"../prompt/index.mjs";import{discoverManifest as i,inferCliName as a}from"../config/package-json.mjs";import{deriveHelpLinks as o}from"./help-links.mjs";import{planInvocation as s}from"./planner.mjs";import{discoverConfig as c}from"../config/index.mjs";const l={jsonMode:!1,isTTY:!1,verbosity:`normal`};function u(e){let t=[],n;for(let r=0;r<e.length;r+=1){let i=e[r];if(i!==void 0){if(i===`--`){t.push(...e.slice(r));break}if(n===void 0&&i.startsWith(`--config=`)){let e=i.slice(9);if(e.length>0){n=e;continue}t.push(i);continue}if(n===void 0&&i===`--config`){let a=e[r+1];if(a!==void 0&&!a.startsWith(`-`)&&a!==`--`){n=a,r+=1;continue}t.push(i);continue}t.push(i)}}return{configPath:n,filteredArgv:t}}function d(e,r){if(r.includes(`--help`)||r.includes(`-h`))return!1;try{let t=n(e,r);return e.args.some(({name:e,schema:n})=>{let r=t.args[e];return n.stdinMode&&(r===void 0||r===`-`)})}catch(e){if(e instanceof t)return!1;throw e}}function f(e,t){let n=s({schema:e,argv:t,help:{binName:e.name},output:l});switch(n.kind){case`match`:return d(n.plan.mergedSchema,n.plan.argv);case`dispatch-error`:case`needs-subcommand`:case`root-help`:case`root-version`:return!1}}function p(e,t){if(!e.hasBuiltInCompletions)return!1;let n=s({schema:e,argv:t,help:{binName:e.name},output:l});return n.kind===`match`&&n.plan.command.schema.name===`completions`}async function m(e,t,n,r){let s=e.packageJsonSettings,c=s!==void 0&&!r?await(async()=>{let n=s.data??await i(t,{...s.from===void 0?{}:{startDir:s.from},files:s.files});if(n===null)return e;let r=s.inferName?a(n,{stripScope:s.stripScope}):void 0;return{...e,...e.version===void 0&&n.version!==void 0?{version:n.version}:{},...e.description===void 0&&n.description!==void 0?{description:n.description}:{},...r===void 0?{}:{name:r},helpLinks:o(e.helpLinks,n,e.version??n.version)}})():e;return n===void 0?c:{...c,name:n}}async function h(t,n,r,i,a){if(t.configSettings===void 0||i||a!==void 0)return a;try{let e=await c(t.configSettings.appName,n,{...r===void 0?{}:{configPath:r},...t.configSettings.loaders===void 0?{}:{loaders:t.configSettings.loaders}});return e.found?e.data:void 0}catch(t){if(t instanceof e)return t;throw t}}async function g(t){let n=t.adapter.argv.slice(2),{configPath:i,filteredArgv:a}=t.schema.configSettings===void 0?{configPath:void 0,filteredArgv:n}:u(n),o=a.includes(`--json`)||t.options?.jsonMode===!0,s=p(t.schema,a),c=await m(t.schema,t.adapter,t.inheritedName,s),l=await h(c,t.adapter,i,s,t.options?.config);if(l instanceof e)return{kind:`config-error`,error:l,jsonMode:o};let d=t.options?.prompter===void 0&&t.adapter.stdinIsTTY?r(t.adapter.stdin,t.adapter.stderr):void 0,g=t.options?.stdinData===void 0&&f(c,a)?await t.adapter.readStdin():t.options?.stdinData;return{kind:`ready`,schema:c,filteredArgv:a,inputs:{env:t.options?.env??t.adapter.env,isTTY:t.options?.isTTY??t.adapter.isTTY,jsonMode:o,verbosity:t.options?.verbosity??`normal`,...g===void 0?{}:{stdinData:g},...t.options?.prompter===void 0?d===void 0?{}:{prompter:d}:{prompter:t.options.prompter},...l===void 0?{}:{config:l}}}}export{g as prepareRuntimePreflight};
1
+ import{CLIError as e,ParseError as t}from"../errors/index.mjs";import{parse as n}from"../parse/index.mjs";import{createTerminalPrompter as r}from"../prompt/index.mjs";import{discoverManifest as i,inferCliName as a}from"../config/package-json.mjs";import{deriveHelpLinks as o}from"./help-links.mjs";import{planInvocation as s}from"./planner.mjs";import{discoverConfig as c}from"../config/index.mjs";const l={jsonMode:!1,isTTY:!1,verbosity:`normal`};function u(e){let t=[],n;for(let r=0;r<e.length;r+=1){let i=e[r];if(i!==void 0){if(i===`--`){t.push(...e.slice(r));break}if(n===void 0&&i.startsWith(`--config=`)){let e=i.slice(9);if(e.length>0){n=e;continue}t.push(i);continue}if(n===void 0&&i===`--config`){let a=e[r+1];if(a!==void 0&&!a.startsWith(`-`)&&a!==`--`){n=a,r+=1;continue}t.push(i);continue}t.push(i)}}return{configPath:n,filteredArgv:t}}function d(e,r){if(r.includes(`--help`)||r.includes(`-h`))return!1;try{let t=n(e,r);return e.args.some(({name:e,schema:n})=>{let r=t.args[e];return n.stdinMode&&(r===void 0||r===`-`)})}catch(e){if(e instanceof t)return!1;throw e}}function f(e,t){let n=s({schema:e,argv:t,help:{binName:e.name},output:l});switch(n.kind){case`match`:return d(n.plan.mergedSchema,n.plan.argv);case`dispatch-error`:case`needs-subcommand`:case`root-help`:case`root-version`:case`root-completions`:return!1}}function p(e,t){if(!e.hasBuiltInCompletions)return!1;let n=s({schema:e,argv:t,help:{binName:e.name},output:l});return n.kind===`match`&&n.plan.command.schema.name===`completions`}async function m(e,t,n,r){let s=e.packageJsonSettings,c=s!==void 0&&!r?await(async()=>{let n=s.data??await i(t,{...s.from===void 0?{}:{startDir:s.from},files:s.files});if(n===null)return e;let r=s.inferName?a(n,{stripScope:s.stripScope}):void 0;return{...e,...e.version===void 0&&n.version!==void 0?{version:n.version}:{},...e.description===void 0&&n.description!==void 0?{description:n.description}:{},...r===void 0?{}:{name:r},helpLinks:o(e.helpLinks,n,e.version??n.version)}})():e;return n===void 0?c:{...c,name:n}}async function h(t,n,r,i,a){if(t.configSettings===void 0||i||a!==void 0)return a;try{let e=await c(t.configSettings.appName,n,{...r===void 0?{}:{configPath:r},...t.configSettings.loaders===void 0?{}:{loaders:t.configSettings.loaders}});return e.found?e.data:void 0}catch(t){if(t instanceof e)return t;throw t}}async function g(t){let n=t.adapter.argv.slice(2),{configPath:i,filteredArgv:a}=t.schema.configSettings===void 0?{configPath:void 0,filteredArgv:n}:u(n),o=a.includes(`--json`)||t.options?.jsonMode===!0,s=p(t.schema,a),c=await m(t.schema,t.adapter,t.inheritedName,s),l=await h(c,t.adapter,i,s,t.options?.config);if(l instanceof e)return{kind:`config-error`,error:l,jsonMode:o};let d=t.options?.prompter===void 0&&t.adapter.stdinIsTTY?r(t.adapter.stdin,t.adapter.stderr):void 0,g=t.options?.stdinData===void 0&&f(c,a)?await t.adapter.readStdin():t.options?.stdinData;return{kind:`ready`,schema:c,filteredArgv:a,inputs:{env:t.options?.env??t.adapter.env,isTTY:t.options?.isTTY??t.adapter.isTTY,jsonMode:o,verbosity:t.options?.verbosity??`normal`,...g===void 0?{}:{stdinData:g},...t.options?.prompter===void 0?d===void 0?{}:{prompter:d}:{prompter:t.options.prompter},...l===void 0?{}:{config:l}}}}export{g as prepareRuntimePreflight};
@@ -22,6 +22,37 @@ type Shell = 'bash' | 'zsh' | 'fish' | 'powershell';
22
22
  * @see {@link Shell} for the union type matching these entries.
23
23
  */
24
24
  declare const SHELLS: Readonly<readonly ['bash', 'zsh', 'fish', 'powershell']>;
25
+ /**
26
+ * Normalize a raw shell token — a bare name (`zsh`), a `$SHELL` path
27
+ * (`/bin/zsh`), or a Windows executable (`…\pwsh.exe`) — to a supported
28
+ * {@link Shell}, or `undefined` when it does not map to one.
29
+ *
30
+ * Mirrors the matching used by the `completions` subcommand so the subcommand
31
+ * and the eager `--completions <shell>` flag accept exactly the same inputs.
32
+ *
33
+ * @param raw - User-supplied shell token or interpreter path.
34
+ * @returns The resolved {@link Shell}, or `undefined` if unrecognized.
35
+ */
36
+ declare function normalizeShell(raw: string): Shell | undefined;
37
+ /**
38
+ * Auto-detect the current shell from environment variables.
39
+ *
40
+ * Resolution order:
41
+ * 1. `$SHELL` parsed as an interpreter path (`/bin/zsh` → `zsh`). It wins when
42
+ * it names a shell we support — a pwsh session launched from bash inherits
43
+ * `SHELL=/bin/bash`, and the login shell the user opted into should be
44
+ * honored over the fallback.
45
+ * 2. Otherwise, the presence of `$PSModulePath` signals PowerShell. PowerShell
46
+ * never sets `$SHELL` on any platform but always exports `PSModulePath` for
47
+ * module discovery, so it is the reliable pwsh signal.
48
+ *
49
+ * Returns `undefined` when no signal resolves, leaving the caller to ask the
50
+ * user for an explicit shell.
51
+ *
52
+ * @param env - Environment record (e.g. `process.env` or an adapter's env).
53
+ * @returns The detected {@link Shell}, or `undefined`.
54
+ */
55
+ declare function detectShell(env: Readonly<Record<string, string | undefined>>): Shell | undefined;
25
56
  /**
26
57
  * Generate a completion script for the given shell.
27
58
  *
@@ -43,4 +74,4 @@ declare const SHELLS: Readonly<readonly ['bash', 'zsh', 'fish', 'powershell']>;
43
74
  */
44
75
  declare function generateCompletion(schema: CLISchema, shell: Shell, options?: CompletionOptions): string;
45
76
  //#endregion
46
- export { type CompletionOptions, SHELLS, type Shell, generateBashCompletion, generateCompletion, generateFishCompletion, generatePowerShellCompletion, generateZshCompletion };
77
+ export { type CompletionOptions, SHELLS, type Shell, detectShell, generateBashCompletion, generateCompletion, generateFishCompletion, generatePowerShellCompletion, generateZshCompletion, normalizeShell };
@@ -1 +1 @@
1
- import{generateBashCompletion as e}from"./shells/bash.mjs";import{generateFishCompletion as t}from"./shells/fish.mjs";import{generatePowerShellCompletion as n}from"./shells/powershell.mjs";import{generateZshCompletion as r}from"./shells/zsh.mjs";const i=Object.freeze([`bash`,`zsh`,`fish`,`powershell`]);function a(i,a,o){switch(a){case`bash`:return e(i,o);case`zsh`:return r(i,o);case`fish`:return t(i,o);case`powershell`:return n(i,o)}}export{i as SHELLS,a as generateCompletion};
1
+ import{generateBashCompletion as e}from"./shells/bash.mjs";import{generateFishCompletion as t}from"./shells/fish.mjs";import{generatePowerShellCompletion as n}from"./shells/powershell.mjs";import{generateZshCompletion as r}from"./shells/zsh.mjs";const i=Object.freeze([`bash`,`zsh`,`fish`,`powershell`]);function a(e){let t=e.split(/[\\/]/),n=(t[t.length-1]??e).replace(/\.(?:exe|cmd|bat)$/i,``);return n===`pwsh`?`powershell`:i.includes(n)?n:void 0}function o(e){let t=e.SHELL,n=t!==void 0&&t!==``?a(t):void 0;if(n!==void 0)return n;if(e.PSModulePath!==void 0)return`powershell`}function s(i,a,o){switch(a){case`bash`:return e(i,o);case`zsh`:return r(i,o);case`fish`:return t(i,o);case`powershell`:return n(i,o)}}export{i as SHELLS,o as detectShell,s as generateCompletion,a as normalizeShell};
@@ -33,6 +33,16 @@ interface CompletionOptions {
33
33
  * ```
34
34
  */
35
35
  readonly functionPrefix?: string;
36
+ /**
37
+ * Where the built-in shell completion is exposed.
38
+ *
39
+ * - `'command'` registers a `completions` subcommand (the default).
40
+ * - `'flag'` exposes an eager `--completions <shell>` flag on the CLI root
41
+ * instead, keeping the root free of a `completions` subcommand.
42
+ *
43
+ * @defaultValue `'command'`
44
+ */
45
+ readonly as?: 'command' | 'flag';
36
46
  /**
37
47
  * Controls which root-level surface shell completion exposes when a
38
48
  * default command exists.
@@ -1 +1 @@
1
- import{collectPropagatedFlags as e}from"../../cli/propagate.mjs";import{resolveRootSurface as t}from"../../cli/root-surface.mjs";import{DREAMCLI_REVISION as n,DREAMCLI_VERSION as r}from"../../../version.mjs";function i(){return`@kjanat/dreamcli v${r}${` (${n})`}`}function a(e,n=`subcommands`){let r=t(e),i=o(e.version!==void 0),a=r.visibleDefaultCommand?.flags??{},s=n===`surface`?r.visibleDefaultCommand!==void 0:r.hasSingleVisibleDefault;return{visibleCommands:r.visibleCommands,visibleDefaultCommand:r.visibleDefaultCommand,rootFlags:i,defaultFlags:a,includeDefaultFlags:s}}function o(e){return{help:s(`Show help text`),...e?{version:s(`Show version`)}:{}}}function s(e){return{kind:`boolean`,presence:`optional`,defaultValue:void 0,aliases:[],envVar:void 0,configPath:void 0,description:e,enumValues:void 0,elementSchema:void 0,prompt:void 0,parseFn:void 0,deprecated:void 0,propagate:!1}}function c(t,n=[]){let r=[];for(let i of t){if(i.hidden)continue;let t=[...n,i],a=e(t),o={...a,...i.flags},s=i.commands.filter(e=>!e.hidden);r.push({path:t.map(e=>e.name),schema:i,propagatedFlags:a,mergedFlags:o,children:s}),s.length>0&&r.push(...c(s,t))}return r}function l(e){let t=e.replace(/[^a-zA-Z0-9_]/g,`_`);if(t===e)return t;let n=2166136261;for(let t=0;t<e.length;t+=1)n^=e.charCodeAt(t),n=Math.imul(n,16777619);return`${t}_${(n>>>0).toString(16).padStart(8,`0`)}`}function u(e){return/^[a-zA-Z0-9_\-.]+$/.test(e)?e:`'${e.replace(/'/g,`'\\''`)}'`}export{u as quoteShellArg,a as resolveRootCompletionSurface,l as sanitizeShellIdentifier,i as versionTag,c as walkCommandTree};
1
+ import{collectPropagatedFlags as e}from"../../cli/propagate.mjs";import{resolveRootSurface as t}from"../../cli/root-surface.mjs";import{DREAMCLI_REVISION as n,DREAMCLI_VERSION as r}from"../../../version.mjs";function i(){return`@kjanat/dreamcli v${r}${` (${n})`}`}function a(e,n=`subcommands`){let r=t(e),i=o(e.version!==void 0),a=r.visibleDefaultCommand?.flags??{},s=n===`surface`?r.hasVisibleDefault:r.hasVisibleDefault&&!r.hasVisibleSubcommands,c=r.visibleDefaultCommand,l=c!==void 0&&r.visibleCommands.some(e=>e.name===c.name);return{visibleCommands:c!==void 0&&!l?[c,...r.visibleCommands]:r.visibleCommands,visibleDefaultCommand:r.visibleDefaultCommand,rootFlags:i,defaultFlags:a,includeDefaultFlags:s}}function o(e){return{help:s(`Show help text`),...e?{version:s(`Show version`)}:{}}}function s(e){return{kind:`boolean`,presence:`optional`,defaultValue:void 0,aliases:[],envVar:void 0,configPath:void 0,description:e,enumValues:void 0,numberConstraints:void 0,elementSchema:void 0,prompt:void 0,parseFn:void 0,deprecated:void 0,propagate:!1}}function c(t,n=[]){let r=[];for(let i of t){if(i.hidden)continue;let t=[...n,i],a=e(t),o={...a,...i.flags},s=i.commands.filter(e=>!e.hidden);r.push({path:t.map(e=>e.name),schema:i,propagatedFlags:a,mergedFlags:o,children:s}),s.length>0&&r.push(...c(s,t))}return r}function l(e){let t=e.replace(/[^a-zA-Z0-9_]/g,`_`);if(t===e)return t;let n=2166136261;for(let t=0;t<e.length;t+=1)n^=e.charCodeAt(t),n=Math.imul(n,16777619);return`${t}_${(n>>>0).toString(16).padStart(8,`0`)}`}function u(e){return/^[a-zA-Z0-9_\-.]+$/.test(e)?e:`'${e.replace(/'/g,`'\\''`)}'`}export{u as quoteShellArg,a as resolveRootCompletionSurface,l as sanitizeShellIdentifier,i as versionTag,c as walkCommandTree};
@@ -15,9 +15,39 @@ interface HelpOptions {
15
15
  * automatically when stdout is a TTY.
16
16
  */
17
17
  readonly hyperlinks?: boolean;
18
+ /**
19
+ * Render the default command's arguments and flags inline in root help.
20
+ *
21
+ * Only affects root-level help. When `false`, root help lists commands and
22
+ * defers default-command details to `<bin> --help`-style hints.
23
+ *
24
+ * @defaultValue `true`
25
+ */
26
+ readonly inlineDefault?: boolean;
27
+ /**
28
+ * List the default command in the root `Commands:` table.
29
+ *
30
+ * By default the default command is treated as the root surface and omitted
31
+ * from the command list (its args/flags render inline instead).
32
+ *
33
+ * @defaultValue `false`
34
+ */
35
+ readonly showDefaultInCommands?: boolean;
36
+ /**
37
+ * Show the `Run '<bin> <command> --help' for more information.` footer.
38
+ *
39
+ * Defaults to showing the hint only when visible subcommands exist; set
40
+ * explicitly to force it on or off.
41
+ */
42
+ readonly footer?: boolean;
18
43
  /** @internal Whether this usage line is being rendered as merged root/default help. */
19
44
  readonly isDefaultHelp?: boolean;
20
45
  }
46
+ /** Formatted flag entry for the flags table. @internal */
47
+ interface FlagEntry {
48
+ readonly left: string;
49
+ readonly description: string;
50
+ }
21
51
  /**
22
52
  * Build the ordered help sections without joining them.
23
53
  *
@@ -53,5 +83,19 @@ declare function formatHelpSections(schema: CommandSchema, options?: HelpOptions
53
83
  * ```
54
84
  */
55
85
  declare function formatHelp(schema: CommandSchema, options?: HelpOptions): string;
86
+ /**
87
+ * Render a titled two-column flag block from pre-built {@link FlagEntry} rows.
88
+ *
89
+ * Shared by the per-command `Flags:` section and the root-help `Global options:`
90
+ * block (built-in flags), so column alignment and description wrapping stay
91
+ * identical across both. Returns `''` when there are no entries.
92
+ *
93
+ * @param title - Section heading (e.g. `'Flags:'`, `'Global options:'`).
94
+ * @param entries - Formatted left/description rows.
95
+ * @param width - Terminal width for description wrapping.
96
+ * @returns Multi-line block string, or `''` when `entries` is empty.
97
+ * @internal
98
+ */
99
+ declare function formatFlagEntriesBlock(title: string, entries: readonly FlagEntry[], width: number): string;
56
100
  //#endregion
57
- export { type HelpOptions, formatHelp, formatHelpSections, osc8, visibleWidth };
101
+ export { type FlagEntry, type HelpOptions, formatFlagEntriesBlock, formatHelp, formatHelpSections, osc8, visibleWidth };
@@ -1,7 +1,7 @@
1
- import{getFlagAliasNames as e}from"../schema/flag.mjs";import{formatDisplayValue as t}from"../output/display-value.mjs";import{padEnd as n,wrapText as r}from"./ansi.mjs";function i(e){return{width:e?.width??80,binName:e?.binName,isDefaultHelp:e?.isDefaultHelp??!1}}function a(e){return typeof e==`string`?`[deprecated: ${e}]`:`[deprecated]`}function o(e){return e===void 0?`undefined`:e===null?`null`:t(e)}function s(t,n){let r=e(n,{kind:`short`}),i=e(n,{kind:`long`}),a=[...r.map(e=>`-${e}`),`--${t}`,...i.map(e=>`--${e}`)];return n.kind===`boolean`?a.join(`, `):`${a.join(`, `)} ${c(n)}`}function c(e){switch(e.kind){case`string`:return`<string>`;case`number`:return`<number>`;case`enum`:return`<${(e.enumValues??[]).join(`|`)}>`;case`array`:return`<${e.elementSchema===void 0?`value`:c(e.elementSchema).slice(1,-1)}>...`;case`boolean`:return``;case`custom`:return`<value>`}}function l(e){let t=[];return e.description!==void 0&&t.push(e.description),e.deprecated!==void 0&&t.push(a(e.deprecated)),e.envVar!==void 0&&t.push(`[env: ${e.envVar}]`),e.configPath!==void 0&&t.push(`[config: ${e.configPath}]`),e.prompt!==void 0&&t.push(`[prompt]`),e.presence===`required`?t.push(`[required]`):e.presence===`defaulted`&&e.kind!==`boolean`&&t.push(`(default: ${o(e.defaultValue)})`),t.join(` `)}function u(t){let n=Object.keys(t);if(n.length===0)return[];let r=[...n].sort((n,r)=>{let i=t[n],a=t[r];if(i===void 0||a===void 0)return 0;let o=e(i,{kind:`short`}).length>0,s=e(a,{kind:`short`}).length>0;return o&&!s?-1:!o&&s?1:n.localeCompare(r)}),i=[];for(let e of r){let n=t[e];n!==void 0&&i.push({left:s(e,n),description:l(n)})}return i}function d(e){let{name:t,schema:n}=e,r=n.kind===`enum`&&n.enumValues!==void 0?n.enumValues.join(`|`):t,i=n.variadic?`...`:``;return n.presence===`required`?`<${r}>${i}`:`[${r}]${i}`}function f(e){let t=[];return e.description!==void 0&&t.push(e.description),e.deprecated!==void 0&&t.push(a(e.deprecated)),e.envVar!==void 0&&t.push(`[env: ${e.envVar}]`),e.presence===`defaulted`&&t.push(`(default: ${o(e.defaultValue)})`),t.join(` `)}function p(e,t){let n=i(t),r=[];r.push(h(e,n)),e.description!==void 0&&r.push(e.description);let a=e.commands.filter(e=>!e.hidden);return a.length>0&&r.push(v(a,n)),e.args.length>0&&r.push(g(e.args,n)),Object.keys(e.flags).length>0&&r.push(_(e.flags,n)),e.examples.length>0&&r.push(y(e.examples)),r}function m(e,t){return`${p(e,t).join(`
1
+ import{getFlagAliasNames as e}from"../schema/flag.mjs";import{formatDisplayValue as t}from"../output/display-value.mjs";import{padEnd as n,wrapText as r}from"./ansi.mjs";function i(e){return{width:e?.width??80,binName:e?.binName,isDefaultHelp:e?.isDefaultHelp??!1}}function a(e){return typeof e==`string`?`[deprecated: ${e}]`:`[deprecated]`}function o(e){return e===void 0?`undefined`:e===null?`null`:t(e)}function s(t,n){let r=e(n,{kind:`short`}),i=e(n,{kind:`long`}),a=[...r.map(e=>`-${e}`),`--${t}`,...i.map(e=>`--${e}`)];return n.kind===`boolean`?a.join(`, `):`${a.join(`, `)} ${c(n)}`}function c(e){switch(e.kind){case`string`:return`<string>`;case`number`:return`<number>`;case`enum`:return`<${(e.enumValues??[]).join(`|`)}>`;case`array`:return`<${e.elementSchema===void 0?`value`:c(e.elementSchema).slice(1,-1)}>...`;case`boolean`:return``;case`custom`:return`<value>`}}function l(e){let t=[];return e.description!==void 0&&t.push(e.description),e.deprecated!==void 0&&t.push(a(e.deprecated)),e.envVar!==void 0&&t.push(`[env: ${e.envVar}]`),e.configPath!==void 0&&t.push(`[config: ${e.configPath}]`),e.prompt!==void 0&&t.push(`[prompt]`),e.presence===`required`?t.push(`[required]`):e.presence===`defaulted`&&e.kind!==`boolean`&&t.push(`(default: ${o(e.defaultValue)})`),t.join(` `)}function u(t){let n=Object.keys(t);if(n.length===0)return[];let r=[...n].sort((n,r)=>{let i=t[n],a=t[r];if(i===void 0||a===void 0)return 0;let o=e(i,{kind:`short`}).length>0,s=e(a,{kind:`short`}).length>0;return o&&!s?-1:!o&&s?1:n.localeCompare(r)}),i=[];for(let e of r){let n=t[e];n!==void 0&&i.push({left:s(e,n),description:l(n)})}return i}function d(e){let{name:t,schema:n}=e,r=n.kind===`enum`&&n.enumValues!==void 0?n.enumValues.join(`|`):t,i=n.variadic?`...`:``;return n.presence===`required`?`<${r}>${i}`:`[${r}]${i}`}function f(e){let t=[];return e.description!==void 0&&t.push(e.description),e.deprecated!==void 0&&t.push(a(e.deprecated)),e.envVar!==void 0&&t.push(`[env: ${e.envVar}]`),e.presence===`defaulted`&&t.push(`(default: ${o(e.defaultValue)})`),t.join(` `)}function p(e,t){let n=i(t),r=[];r.push(h(e,n)),e.description!==void 0&&r.push(e.description);let a=e.commands.filter(e=>!e.hidden);return a.length>0&&r.push(y(a,n)),e.args.length>0&&r.push(g(e.args,n)),Object.keys(e.flags).length>0&&r.push(_(e.flags,n)),e.examples.length>0&&r.push(b(e.examples)),r}function m(e,t){return`${p(e,t).join(`
2
2
 
3
- `)}\n`}function h(e,t){let n=[`Usage:`],r=t.binName===void 0||t.isDefaultHelp&&t.binName===e.name?e.name:`${t.binName} ${e.name}`;n.push(r),e.commands.length>0&&n.push(`<command>`),Object.keys(e.flags).length>0&&n.push(`[flags]`);for(let t of e.args)n.push(d(t));return n.join(` `)}function g(e,t){let i=[`Arguments:`],a=0,o=[];for(let t of e){let e=` ${d(t)}`,n=f(t.schema);o.push({left:e,desc:n}),e.length>a&&(a=e.length)}let s=a+2;for(let{left:e,desc:a}of o)if(a.length===0)i.push(e);else{let o=n(e,s),c=r(a,t.width,s);i.push(`${o}${c}`)}return i.join(`
4
- `)}function _(e,t){let i=[`Flags:`],a=u(e);if(a.length===0)return``;let o=0;for(let e of a){let t=` ${e.left}`;t.length>o&&(o=t.length)}let s=o+2;for(let e of a){let a=` ${e.left}`;if(e.description.length===0)i.push(a);else{let o=n(a,s),c=r(e.description,t.width,s);i.push(`${o}${c}`)}}return i.join(`
5
- `)}function v(e,t){let i=[`Commands:`],a=0;for(let t of e)t.name.length>a&&(a=t.name.length);let o=2+a+2;for(let a of e){let e=` ${a.name}`,s=a.description??``;if(s.length===0)i.push(e);else{let a=n(e,o),c=r(s,t.width,o);i.push(`${a}${c}`)}}return i.join(`
6
- `)}function y(e){let t=[`Examples:`];for(let n of e)n.description===void 0?t.push(` $ ${n.command}`):(t.push(` ${n.description}:`),t.push(` $ ${n.command}`));return t.join(`
7
- `)}export{m as formatHelp,p as formatHelpSections};
3
+ `)}\n`}function h(e,t){let n=[`Usage:`],r=t.binName===void 0?e.name:t.isDefaultHelp?t.binName:`${t.binName} ${e.name}`;n.push(r),e.commands.length>0&&n.push(`<command>`),Object.keys(e.flags).length>0&&n.push(`[flags]`);for(let t of e.args)n.push(d(t));return n.join(` `)}function g(e,t){let i=[`Arguments:`],a=0,o=[];for(let t of e){let e=` ${d(t)}`,n=f(t.schema);o.push({left:e,desc:n}),e.length>a&&(a=e.length)}let s=a+2;for(let{left:e,desc:a}of o)if(a.length===0)i.push(e);else{let o=n(e,s),c=r(a,t.width,s);i.push(`${o}${c}`)}return i.join(`
4
+ `)}function _(e,t){return v(`Flags:`,u(e),t.width)}function v(e,t,i){if(t.length===0)return``;let a=[e],o=0;for(let e of t){let t=` ${e.left}`;t.length>o&&(o=t.length)}let s=o+2;for(let e of t){let t=` ${e.left}`;if(e.description.length===0)a.push(t);else{let o=n(t,s),c=r(e.description,i,s);a.push(`${o}${c}`)}}return a.join(`
5
+ `)}function y(e,t){let i=[`Commands:`],a=0;for(let t of e)t.name.length>a&&(a=t.name.length);let o=2+a+2;for(let a of e){let e=` ${a.name}`,s=a.description??``;if(s.length===0)i.push(e);else{let a=n(e,o),c=r(s,t.width,o);i.push(`${a}${c}`)}}return i.join(`
6
+ `)}function b(e){let t=[`Examples:`];for(let n of e)n.description===void 0?t.push(` $ ${n.command}`):(t.push(` ${n.description}:`),t.push(` $ ${n.command}`));return t.join(`
7
+ `)}export{v as formatFlagEntriesBlock,m as formatHelp,p as formatHelpSections};
@@ -1,4 +1,4 @@
1
- import{getFlagAliasNames as e}from"../schema/flag.mjs";import{parseSchema as t}from"../schema-dsl/runtime.mjs";import{nodeToJsonSchema as n}from"../schema-dsl/to-json-schema.mjs";import{definitionMetaSchemaDescriptions as r}from"./meta-descriptions.generated.mjs";function i(e){return{includeHidden:e?.includeHidden??!0,includePrompts:e?.includePrompts??!0}}const a=`https://cdn.jsdelivr.net/npm/@kjanat/dreamcli/dreamcli.schema.json`,o=`https://json-schema.org/draft/2020-12/schema`;function s(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function c(e,t){let n=i(t),r={$schema:a,name:e.name};return e.version!==void 0&&(r.version=e.version),e.description!==void 0&&(r.description=e.description),e.defaultCommand!==void 0&&(n.includeHidden||!e.defaultCommand.schema.hidden)&&(r.defaultCommand=e.defaultCommand.schema.name),r.commands=e.commands.filter(e=>n.includeHidden||!e.schema.hidden).map(e=>l(e.schema,n)),r}function l(e,t){let n={name:e.name};e.description!==void 0&&(n.description=e.description),e.aliases.length>0&&(n.aliases=[...e.aliases]),e.hidden&&(n.hidden=!0),e.examples.length>0&&(n.examples=e.examples.map(m));let r={};for(let[n,i]of Object.entries(e.flags))r[n]=u(i,t);return n.flags=r,n.args=e.args.map(d),n.commands=e.commands.filter(e=>t.includeHidden||!e.hidden).map(e=>l(e,t)),n}function u(t,n){let r={kind:t.kind,presence:t.presence};t.presence===`defaulted`&&w(t.defaultValue)&&(r.defaultValue=t.defaultValue);let i=e(t);return i.length>0&&(r.aliases=[...i]),t.envVar!==void 0&&(r.envVar=t.envVar),t.configPath!==void 0&&(r.configPath=t.configPath),t.description!==void 0&&(r.description=t.description),t.enumValues!==void 0&&(r.enumValues=[...t.enumValues]),t.elementSchema!==void 0&&(r.elementSchema=u(t.elementSchema,n)),n.includePrompts&&t.prompt!==void 0&&(r.prompt=f(t.prompt)),t.deprecated!==void 0&&(r.deprecated=t.deprecated),t.propagate&&(r.propagate=!0),r}function d(e){let{name:t,schema:n}=e,r={name:t,kind:n.kind,presence:n.presence};return n.variadic&&(r.variadic=!0),n.stdinMode&&(r.stdinMode=!0),n.presence===`defaulted`&&w(n.defaultValue)&&(r.defaultValue=n.defaultValue),n.description!==void 0&&(r.description=n.description),n.envVar!==void 0&&(r.envVar=n.envVar),n.enumValues!==void 0&&(r.enumValues=[...n.enumValues]),n.deprecated!==void 0&&(r.deprecated=n.deprecated),r}function f(e){let t={kind:e.kind,message:e.message};switch(e.kind){case`input`:e.placeholder!==void 0&&(t.placeholder=e.placeholder);break;case`select`:e.choices!==void 0&&(t.choices=e.choices.map(p));break;case`multiselect`:e.choices!==void 0&&(t.choices=e.choices.map(p)),e.min!==void 0&&(t.min=e.min),e.max!==void 0&&(t.max=e.max);break;case`confirm`:break}return t}function p(e){let t={value:e.value};return e.label!==void 0&&(t.label=e.label),e.description!==void 0&&(t.description=e.description),t}function m(e){let t={command:e.command};return e.description!==void 0&&(t.description=e.description),t}function h(e,t){let n=i(t);if(g(e))return{$schema:o,...v(e)};let r=[];for(let t of e.commands)!n.includeHidden&&t.schema.hidden||_(t.schema,``,r,n);if(r.length===1)return{$schema:o,...y(r[0]??{})};if(r.length>0){let t=e.defaultCommand!==void 0&&(n.includeHidden||!e.defaultCommand.schema.hidden)?e.defaultCommand.schema.name:void 0;return{$schema:o,oneOf:t===void 0?r:r.map(e=>b(e)===t?y(e):e)}}return{$schema:o,type:`object`}}function g(e){return`flags`in e&&`args`in e&&`middleware`in e&&`hasAction`in e}function _(e,t,n,r){let i=t?`${t}.${e.name}`:e.name;e.hasAction&&n.push(v(e,i));for(let t of e.commands)!r.includeHidden&&t.hidden||_(t,i,n,r)}function v(e,t){let n={},r=[];t!==void 0&&(n.command={const:t},r.push(`command`));for(let[t,i]of Object.entries(e.flags))n[t]=x(i),i.presence===`required`&&r.push(t);for(let t of e.args)n[t.name]=S(t.schema),t.schema.presence===`required`&&r.push(t.name);let i={type:`object`,properties:n,additionalProperties:!1};return r.length>0&&(i.required=r),i}function y(e){let t=e.properties,n=e.required,r=s(t)?{...t}:void 0,i=Array.isArray(n)?n.filter(e=>typeof e==`string`):void 0;r!==void 0&&delete r.command;let a=i?.filter(e=>e!==`command`),o={...e};return r!==void 0&&(o.properties=r),a!==void 0&&a.length>0?o.required=a:delete o.required,o}function b(e){let t=e.properties;if(!s(t))return;let n=t.command;return s(n)&&typeof n.const==`string`?n.const:void 0}function x(e){let t={};switch(e.kind){case`string`:t.type=`string`;break;case`number`:t.type=`number`;break;case`boolean`:t.type=`boolean`;break;case`enum`:t.type=`string`,e.enumValues!==void 0&&(t.enum=[...e.enumValues]);break;case`array`:t.type=`array`,e.elementSchema!==void 0&&(t.items=x(e.elementSchema));break;case`custom`:break}return e.description!==void 0&&(t.description=e.description),e.presence===`defaulted`&&w(e.defaultValue)&&(t.default=e.defaultValue),e.deprecated!==void 0&&(t.deprecated=e.deprecated),t}function S(e){let t=C(e),n=e.variadic?{type:`array`,items:t}:{...t};return e.description!==void 0&&(n.description=e.description),e.presence===`defaulted`&&w(e.defaultValue)&&(n.default=e.defaultValue),e.deprecated!==void 0&&(n.deprecated=e.deprecated),n}function C(e){switch(e.kind){case`string`:return{type:`string`};case`number`:return{type:`number`};case`enum`:{let t={type:`string`};return e.enumValues!==void 0&&(t.enum=[...e.enumValues]),t}case`custom`:return{}}}function w(e,t=new WeakSet){if(e===void 0)return!1;if(e===null)return!0;let n=typeof e;if(n===`string`||n===`boolean`)return!0;if(n===`number`)return Number.isFinite(e);if(n===`function`||n===`symbol`||n===`bigint`)return!1;if(Array.isArray(e)){if(t.has(e))return!1;t.add(e);try{return e.every(e=>w(e,t))}finally{t.delete(e)}}if(n===`object`){let n=e;if(!T(n)||t.has(n))return!1;t.add(n);try{return Object.values(n).every(e=>w(e,t))}finally{t.delete(n)}}return!1}function T(e){let t=Object.getPrototypeOf(e);return t===Object.prototype||t===null}function E(e){return n(t(e))}function D(e,t){let n=e.properties,r=typeof n==`object`&&n&&T(n)&&t.properties!==void 0?Object.fromEntries(Object.entries(n).map(([e,n])=>{let r=t.properties?.[e];return r===void 0||typeof n!=`object`||!n||!T(n)?[e,n]:[e,D(n,r)]})):void 0;return{...e,...t.description===void 0?{}:{description:t.description},...r===void 0?{}:{properties:r}}}function O(e,t){let n=D(e,t.root),r=n.$defs;return typeof r!=`object`||!r||!T(r)?n:{...n,$defs:Object.fromEntries(Object.entries(r).map(([e,n])=>{let r=t.defs[e];return r===void 0||typeof n!=`object`||!n||!T(n)?[e,n]:[e,D(n,r)]}))}}const k=O({$schema:o,$id:a,title:`@kjanat/dreamcli definition schema`,description:`Describes the structure of a CLI built with dreamcli — commands, flags, args, types, constraints, env bindings, and prompts.`,...E(`{
1
+ import{getFlagAliasNames as e}from"../schema/flag.mjs";import{parseSchema as t}from"../schema-dsl/runtime.mjs";import{nodeToJsonSchema as n}from"../schema-dsl/to-json-schema.mjs";import{definitionMetaSchemaDescriptions as r}from"./meta-descriptions.generated.mjs";function i(e){return{includeHidden:e?.includeHidden??!0,includePrompts:e?.includePrompts??!0}}const a=`https://cdn.jsdelivr.net/npm/@kjanat/dreamcli/dreamcli.schema.json`,o=`https://json-schema.org/draft/2020-12/schema`;function s(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function c(e,t){let n=i(t),r={$schema:a,name:e.name};return e.version!==void 0&&(r.version=e.version),e.description!==void 0&&(r.description=e.description),e.defaultCommand!==void 0&&(n.includeHidden||!e.defaultCommand.schema.hidden)&&(r.defaultCommand=e.defaultCommand.schema.name),r.commands=e.commands.filter(e=>n.includeHidden||!e.schema.hidden).map(e=>l(e.schema,n)),r}function l(e,t){let n={name:e.name};e.description!==void 0&&(n.description=e.description),e.aliases.length>0&&(n.aliases=[...e.aliases]),e.hidden&&(n.hidden=!0),e.examples.length>0&&(n.examples=e.examples.map(m));let r={};for(let[n,i]of Object.entries(e.flags))r[n]=u(i,t);return n.flags=r,n.args=e.args.map(d),n.commands=e.commands.filter(e=>t.includeHidden||!e.hidden).map(e=>l(e,t)),n}function u(t,n){let r={kind:t.kind,presence:t.presence};t.presence===`defaulted`&&w(t.defaultValue)&&(r.defaultValue=t.defaultValue);let i=e(t);return i.length>0&&(r.aliases=[...i]),t.envVar!==void 0&&(r.envVar=t.envVar),t.configPath!==void 0&&(r.configPath=t.configPath),t.description!==void 0&&(r.description=t.description),t.enumValues!==void 0&&(r.enumValues=[...t.enumValues]),t.elementSchema!==void 0&&(r.elementSchema=u(t.elementSchema,n)),n.includePrompts&&t.prompt!==void 0&&(r.prompt=f(t.prompt)),t.deprecated!==void 0&&(r.deprecated=t.deprecated),t.propagate&&(r.propagate=!0),r}function d(e){let{name:t,schema:n}=e,r={name:t,kind:n.kind,presence:n.presence};return n.variadic&&(r.variadic=!0),n.stdinMode&&(r.stdinMode=!0),n.presence===`defaulted`&&w(n.defaultValue)&&(r.defaultValue=n.defaultValue),n.description!==void 0&&(r.description=n.description),n.envVar!==void 0&&(r.envVar=n.envVar),n.enumValues!==void 0&&(r.enumValues=[...n.enumValues]),n.deprecated!==void 0&&(r.deprecated=n.deprecated),r}function f(e){let t={kind:e.kind,message:e.message};switch(e.kind){case`input`:e.placeholder!==void 0&&(t.placeholder=e.placeholder);break;case`select`:e.choices!==void 0&&(t.choices=e.choices.map(p));break;case`multiselect`:e.choices!==void 0&&(t.choices=e.choices.map(p)),e.min!==void 0&&(t.min=e.min),e.max!==void 0&&(t.max=e.max);break;case`confirm`:break}return t}function p(e){let t={value:e.value};return e.label!==void 0&&(t.label=e.label),e.description!==void 0&&(t.description=e.description),t}function m(e){let t={command:e.command};return e.description!==void 0&&(t.description=e.description),t}function h(e,t){let n=i(t);if(g(e))return{$schema:o,...v(e)};let r=[];for(let t of e.commands)!n.includeHidden&&t.schema.hidden||_(t.schema,``,r,n);if(r.length===1)return{$schema:o,...y(r[0]??{})};if(r.length>0){let t=e.defaultCommand!==void 0&&(n.includeHidden||!e.defaultCommand.schema.hidden)?e.defaultCommand.schema.name:void 0;return{$schema:o,oneOf:t===void 0?r:r.map(e=>b(e)===t?y(e):e)}}return{$schema:o,type:`object`}}function g(e){return`flags`in e&&`args`in e&&`middleware`in e&&`hasAction`in e}function _(e,t,n,r){let i=t?`${t}.${e.name}`:e.name;e.hasAction&&n.push(v(e,i));for(let t of e.commands)!r.includeHidden&&t.hidden||_(t,i,n,r)}function v(e,t){let n={},r=[];t!==void 0&&(n.command={const:t},r.push(`command`));for(let[t,i]of Object.entries(e.flags))n[t]=x(i),i.presence===`required`&&r.push(t);for(let t of e.args)n[t.name]=S(t.schema),t.schema.presence===`required`&&r.push(t.name);let i={type:`object`,properties:n,additionalProperties:!1};return r.length>0&&(i.required=r),i}function y(e){let t=e.properties,n=e.required,r=s(t)?{...t}:void 0,i=Array.isArray(n)?n.filter(e=>typeof e==`string`):void 0;r!==void 0&&delete r.command;let a=i?.filter(e=>e!==`command`),o={...e};return r!==void 0&&(o.properties=r),a!==void 0&&a.length>0?o.required=a:delete o.required,o}function b(e){let t=e.properties;if(!s(t))return;let n=t.command;return s(n)&&typeof n.const==`string`?n.const:void 0}function x(e){let t={};switch(e.kind){case`string`:t.type=`string`;break;case`number`:{let n=e.numberConstraints;t.type=n?.int===!0?`integer`:`number`,n?.min!==void 0&&(t.minimum=n.min),n?.max!==void 0&&(t.maximum=n.max);break}case`boolean`:t.type=`boolean`;break;case`enum`:t.type=`string`,e.enumValues!==void 0&&(t.enum=[...e.enumValues]);break;case`array`:t.type=`array`,e.elementSchema!==void 0&&(t.items=x(e.elementSchema));break;case`custom`:break}return e.description!==void 0&&(t.description=e.description),e.presence===`defaulted`&&w(e.defaultValue)&&(t.default=e.defaultValue),e.deprecated!==void 0&&(t.deprecated=e.deprecated),t}function S(e){let t=C(e),n=e.variadic?{type:`array`,items:t}:{...t};return e.description!==void 0&&(n.description=e.description),e.presence===`defaulted`&&w(e.defaultValue)&&(n.default=e.defaultValue),e.deprecated!==void 0&&(n.deprecated=e.deprecated),n}function C(e){switch(e.kind){case`string`:return{type:`string`};case`number`:{let t=e.numberConstraints,n={type:t?.int===!0?`integer`:`number`};return t?.min!==void 0&&(n.minimum=t.min),t?.max!==void 0&&(n.maximum=t.max),n}case`enum`:{let t={type:`string`};return e.enumValues!==void 0&&(t.enum=[...e.enumValues]),t}case`custom`:return{}}}function w(e,t=new WeakSet){if(e===void 0)return!1;if(e===null)return!0;let n=typeof e;if(n===`string`||n===`boolean`)return!0;if(n===`number`)return Number.isFinite(e);if(n===`function`||n===`symbol`||n===`bigint`)return!1;if(Array.isArray(e)){if(t.has(e))return!1;t.add(e);try{return e.every(e=>w(e,t))}finally{t.delete(e)}}if(n===`object`){let n=e;if(!T(n)||t.has(n))return!1;t.add(n);try{return Object.values(n).every(e=>w(e,t))}finally{t.delete(n)}}return!1}function T(e){let t=Object.getPrototypeOf(e);return t===Object.prototype||t===null}function E(e){return n(t(e))}function D(e,t){let n=e.properties,r=typeof n==`object`&&n&&T(n)&&t.properties!==void 0?Object.fromEntries(Object.entries(n).map(([e,n])=>{let r=t.properties?.[e];return r===void 0||typeof n!=`object`||!n||!T(n)?[e,n]:[e,D(n,r)]})):void 0;return{...e,...t.description===void 0?{}:{description:t.description},...r===void 0?{}:{properties:r}}}function O(e,t){let n=D(e,t.root),r=n.$defs;return typeof r!=`object`||!r||!T(r)?n:{...n,$defs:Object.fromEntries(Object.entries(r).map(([e,n])=>{let r=t.defs[e];return r===void 0||typeof n!=`object`||!n||!T(n)?[e,n]:[e,D(n,r)]}))}}const k=O({$schema:o,$id:a,title:`@kjanat/dreamcli definition schema`,description:`Describes the structure of a CLI built with dreamcli — commands, flags, args, types, constraints, env bindings, and prompts.`,...E(`{
2
2
  $schema: '${a}';
3
3
  name: string;
4
4
  version?: string;
@@ -6,22 +6,22 @@
6
6
  */
7
7
  declare const definitionMetaSchemaDescriptions: {
8
8
  readonly root: {
9
- readonly description: "Runtime descriptor for the CLI program.\n\nStores the program name, version, description, and registered commands.\\\nBuilt incrementally by CLIBuilder.";
9
+ readonly description: 'Runtime descriptor for the CLI program.\n\nStores the program name, version, description, and registered commands.\\\nBuilt incrementally by CLIBuilder.';
10
10
  readonly properties: {
11
11
  readonly name: {
12
- readonly description: "Program name (used in help text, usage lines, and completion scripts).";
12
+ readonly description: 'Program name (used in help text, usage lines, and completion scripts).';
13
13
  };
14
14
  readonly version: {
15
- readonly description: "Program version (shown by `--version`).";
15
+ readonly description: 'Program version (shown by `--version`).';
16
16
  };
17
17
  readonly description: {
18
- readonly description: "Program description (shown in root help).";
18
+ readonly description: 'Program description (shown in root help).';
19
19
  };
20
20
  readonly defaultCommand: {
21
- readonly description: "Default command dispatched when no subcommand matches.\n\nWhen set, the CLI root behaves like a hybrid command group: subcommands\ndispatch by name as usual, but empty argv or flags-only argv falls\nthrough to this command instead of showing root help.\n\nSet via the .default() builder method.";
21
+ readonly description: 'Default command dispatched when no subcommand matches.\n\nWhen set, the CLI root behaves like a hybrid command group: subcommands\ndispatch by name as usual, but empty argv or flags-only argv falls\nthrough to this command instead of showing root help.\n\nSet via the .default() builder method.';
22
22
  };
23
23
  readonly commands: {
24
- readonly description: "Registered commands (type-erased for heterogeneous storage).";
24
+ readonly description: 'Registered commands (type-erased for heterogeneous storage).';
25
25
  };
26
26
  };
27
27
  };
@@ -33,25 +33,25 @@ declare const definitionMetaSchemaDescriptions: {
33
33
  readonly description: "The command name (used for dispatch, e.g. `'deploy'`).";
34
34
  };
35
35
  readonly description: {
36
- readonly description: "Human-readable description for help text.";
36
+ readonly description: 'Human-readable description for help text.';
37
37
  };
38
38
  readonly aliases: {
39
- readonly description: "Alternative names for this command.";
39
+ readonly description: 'Alternative names for this command.';
40
40
  };
41
41
  readonly hidden: {
42
- readonly description: "Whether this command is hidden from help listings.";
42
+ readonly description: 'Whether this command is hidden from help listings.';
43
43
  };
44
44
  readonly examples: {
45
- readonly description: "Usage examples for help text.";
45
+ readonly description: 'Usage examples for help text.';
46
46
  };
47
47
  readonly flags: {
48
- readonly description: "Named flag schemas, keyed by flag name.";
48
+ readonly description: 'Named flag schemas, keyed by flag name.';
49
49
  };
50
50
  readonly args: {
51
- readonly description: "Ordered positional arg entries (name + schema).";
51
+ readonly description: 'Ordered positional arg entries (name + schema).';
52
52
  };
53
53
  readonly commands: {
54
- readonly description: "Nested subcommand schemas (for help rendering and completion).\n\nPure data — no execution closures. Populated by `.command()` on\n`CommandBuilder`. Empty for leaf commands.";
54
+ readonly description: 'Nested subcommand schemas (for help rendering and completion).\n\nPure data — no execution closures. Populated by `.command()` on\n`CommandBuilder`. Empty for leaf commands.';
55
55
  };
56
56
  };
57
57
  };
@@ -59,25 +59,25 @@ declare const definitionMetaSchemaDescriptions: {
59
59
  readonly description: "The runtime descriptor stored inside every FlagBuilder. Consumers (parser,\nhelp generator, resolution chain) read this to understand the flag's shape\nwithout touching generics.";
60
60
  readonly properties: {
61
61
  readonly kind: {
62
- readonly description: "What kind of value this flag accepts.";
62
+ readonly description: 'What kind of value this flag accepts.';
63
63
  };
64
64
  readonly presence: {
65
65
  readonly description: "Presence describes whether a flag value is guaranteed to exist when the\naction handler runs:\n\n- `'optional'` — not required; unresolved value follows the kind-specific\n optional fallback (`undefined` for most flags, `[]` for arrays)\n- `'required'` — must be supplied; error if missing\n- `'defaulted'` — always present (falls back to default value)";
66
66
  };
67
67
  readonly defaultValue: {
68
- readonly description: "Runtime default value (if any).";
68
+ readonly description: 'Runtime default value (if any).';
69
69
  };
70
70
  readonly aliases: {
71
71
  readonly description: "Short/long aliases (e.g. `[{ name: 'f', hidden: false }]` for `--force`).";
72
72
  };
73
73
  readonly envVar: {
74
- readonly description: "Environment variable name for v0.2+ resolution.";
74
+ readonly description: 'Environment variable name for v0.2+ resolution.';
75
75
  };
76
76
  readonly configPath: {
77
77
  readonly description: "Dotted config path for v0.2+ resolution (e.g. `'deploy.region'`).";
78
78
  };
79
79
  readonly description: {
80
- readonly description: "Human-readable description for help text.";
80
+ readonly description: 'Human-readable description for help text.';
81
81
  };
82
82
  readonly enumValues: {
83
83
  readonly description: "Allowed literal values when `kind === 'enum'`.";
@@ -86,13 +86,13 @@ declare const definitionMetaSchemaDescriptions: {
86
86
  readonly description: "Element schema when `kind === 'array'`.";
87
87
  };
88
88
  readonly prompt: {
89
- readonly description: "Interactive prompt configuration for v0.3+ resolution.";
89
+ readonly description: 'Interactive prompt configuration for v0.3+ resolution.';
90
90
  };
91
91
  readonly deprecated: {
92
- readonly description: "Deprecation marker.\n\n- `undefined` — not deprecated (default)\n- `true` — deprecated with no migration message\n- `string` — deprecated with a reason/migration message\n\nWhen a deprecated flag is used, a warning is emitted to stderr.\nHelp text shows `[deprecated]` or `[deprecated: <reason>]`.";
92
+ readonly description: 'Deprecation marker.\n\n- `undefined` — not deprecated (default)\n- `true` — deprecated with no migration message\n- `string` — deprecated with a reason/migration message\n\nWhen a deprecated flag is used, a warning is emitted to stderr.\nHelp text shows `[deprecated]` or `[deprecated: <reason>]`.';
93
93
  };
94
94
  readonly propagate: {
95
- readonly description: "Whether this flag propagates to subcommands in nested command trees.\n\nWhen `true`, the flag is automatically available to all descendant\ncommands. A child command that defines a flag with the same name\nshadows the propagated parent flag.";
95
+ readonly description: 'Whether this flag propagates to subcommands in nested command trees.\n\nWhen `true`, the flag is automatically available to all descendant\ncommands. A child command that defines a flag with the same name\nshadows the propagated parent flag.';
96
96
  };
97
97
  };
98
98
  };
@@ -100,25 +100,25 @@ declare const definitionMetaSchemaDescriptions: {
100
100
  readonly description: "The runtime descriptor stored inside every ArgBuilder. Consumers (parser,\nhelp generator) read this to understand the arg's shape without touching\ngenerics.";
101
101
  readonly properties: {
102
102
  readonly name: {
103
- readonly description: "A named positional argument entry in the command schema.\n\nPairs a user-facing arg name with its ArgSchema descriptor.\nThe array ordering in CommandSchema.args determines CLI position.";
103
+ readonly description: 'A named positional argument entry in the command schema.\n\nPairs a user-facing arg name with its ArgSchema descriptor.\nThe array ordering in CommandSchema.args determines CLI position.';
104
104
  };
105
105
  readonly kind: {
106
- readonly description: "What kind of value this arg accepts.";
106
+ readonly description: 'What kind of value this arg accepts.';
107
107
  };
108
108
  readonly presence: {
109
109
  readonly description: "Presence describes whether a positional arg is guaranteed to exist when the\naction handler runs:\n\n- `'required'` — must be supplied; error if missing (default)\n- `'optional'` — may be `undefined` if not supplied\n- `'defaulted'` — always present (falls back to default value)";
110
110
  };
111
111
  readonly variadic: {
112
- readonly description: "Whether this arg consumes all remaining positionals.";
112
+ readonly description: 'Whether this arg consumes all remaining positionals.';
113
113
  };
114
114
  readonly stdinMode: {
115
- readonly description: "Whether this arg may read from stdin during resolution.";
115
+ readonly description: 'Whether this arg may read from stdin during resolution.';
116
116
  };
117
117
  readonly defaultValue: {
118
- readonly description: "Runtime default value (if any).";
118
+ readonly description: 'Runtime default value (if any).';
119
119
  };
120
120
  readonly description: {
121
- readonly description: "Human-readable description for help text.";
121
+ readonly description: 'Human-readable description for help text.';
122
122
  };
123
123
  readonly envVar: {
124
124
  readonly description: "Environment variable name for env resolution.\n\nWhen set and the CLI value is absent, the resolver reads this env var\nand coerces the string to the arg's declared kind.";
@@ -127,7 +127,7 @@ declare const definitionMetaSchemaDescriptions: {
127
127
  readonly description: "Allowed literal values when `kind === 'enum'`.";
128
128
  };
129
129
  readonly deprecated: {
130
- readonly description: "Deprecation marker.\n\n- `undefined` — not deprecated (default)\n- `true` — deprecated with no migration message\n- `string` — deprecated with a reason/migration message\n\nWhen a deprecated arg is used, a warning is emitted to stderr.\nHelp text shows `[deprecated]` or `[deprecated: <reason>]`.";
130
+ readonly description: 'Deprecation marker.\n\n- `undefined` — not deprecated (default)\n- `true` — deprecated with no migration message\n- `string` — deprecated with a reason/migration message\n\nWhen a deprecated arg is used, a warning is emitted to stderr.\nHelp text shows `[deprecated]` or `[deprecated: <reason>]`.';
131
131
  };
132
132
  };
133
133
  };
@@ -138,44 +138,44 @@ declare const definitionMetaSchemaDescriptions: {
138
138
  readonly description: "The kind of interactive prompt to present.\n\n- `'confirm'` — yes/no boolean question\n- `'input'` — free-text string input\n- `'select'` — single selection from a list\n- `'multiselect'` — multiple selections from a list";
139
139
  };
140
140
  readonly message: {
141
- readonly description: "The question displayed to the user.";
141
+ readonly description: 'The question displayed to the user.';
142
142
  };
143
143
  readonly placeholder: {
144
- readonly description: "Placeholder text shown before user types (informational only).";
144
+ readonly description: 'Placeholder text shown before user types (informational only).';
145
145
  };
146
146
  readonly choices: {
147
- readonly description: "Available choices. When omitted for `enum` flags, the enum values\nfrom the flag schema are used automatically.";
147
+ readonly description: 'Available choices. When omitted for `enum` flags, the enum values\nfrom the flag schema are used automatically.';
148
148
  };
149
149
  readonly min: {
150
- readonly description: "Minimum number of selections required.";
150
+ readonly description: 'Minimum number of selections required.';
151
151
  };
152
152
  readonly max: {
153
- readonly description: "Maximum number of selections allowed.";
153
+ readonly description: 'Maximum number of selections allowed.';
154
154
  };
155
155
  };
156
156
  };
157
157
  readonly choice: {
158
- readonly description: "A selectable option for SelectPromptConfig and MultiselectPromptConfig prompts.";
158
+ readonly description: 'A selectable option for SelectPromptConfig and MultiselectPromptConfig prompts.';
159
159
  readonly properties: {
160
160
  readonly value: {
161
- readonly description: "The value returned when this choice is selected.";
161
+ readonly description: 'The value returned when this choice is selected.';
162
162
  };
163
163
  readonly label: {
164
- readonly description: "Display label shown to the user.";
164
+ readonly description: 'Display label shown to the user.';
165
165
  };
166
166
  readonly description: {
167
- readonly description: "Optional description shown alongside the choice.";
167
+ readonly description: 'Optional description shown alongside the choice.';
168
168
  };
169
169
  };
170
170
  };
171
171
  readonly example: {
172
- readonly description: "A single usage example shown in help text.";
172
+ readonly description: 'A single usage example shown in help text.';
173
173
  readonly properties: {
174
174
  readonly command: {
175
175
  readonly description: "The command invocation (e.g. `'deploy production --force'`).";
176
176
  };
177
177
  readonly description: {
178
- readonly description: "Optional description of what this example does.";
178
+ readonly description: 'Optional description of what this example does.';
179
179
  };
180
180
  };
181
181
  };
@@ -58,6 +58,20 @@ declare function tokenize(argv: readonly string[]): readonly Token[];
58
58
  * @returns `true` if `token` occurs before any `--` separator.
59
59
  */
60
60
  declare function includesBeforeSeparator(argv: readonly string[], token: string): boolean;
61
+ /**
62
+ * Remove every occurrence of `token` that appears before the `--` end-of-options
63
+ * separator, leaving post-separator literals untouched.
64
+ *
65
+ * The strip counterpart to {@linkcode includesBeforeSeparator}: root-level flags
66
+ * (`--json`) are stripped before dispatch/parse so the command schema never sees
67
+ * them, but a literal after `--` (`-- --json`) must reach the command unchanged.
68
+ *
69
+ * @param argv - Raw argument strings.
70
+ * @param token - Exact flag token to strip (e.g. `--json`).
71
+ * @returns A new argv with pre-separator occurrences of `token` removed, or the
72
+ * original reference when `token` does not occur before the separator.
73
+ */
74
+ declare function stripBeforeSeparator(argv: readonly string[], token: string): readonly string[];
61
75
  /**
62
76
  * Raw parsed values before resolution (defaults, env, config, etc.).
63
77
  *
@@ -106,4 +120,4 @@ declare function flagExpectsValue(schema: FlagSchema): boolean;
106
120
  */
107
121
  declare function parse(schema: CommandSchema, argv: readonly string[]): ParseResult;
108
122
  //#endregion
109
- export { type ParseResult, type Token, buildFlagLookup, flagExpectsValue, includesBeforeSeparator, parse, tokenize };
123
+ export { type ParseResult, type Token, buildFlagLookup, flagExpectsValue, includesBeforeSeparator, parse, stripBeforeSeparator, tokenize };
@@ -1 +1 @@
1
- import{getFlagAliasNames as e}from"../schema/flag.mjs";import{ParseError as t}from"../errors/index.mjs";function n(e){let t=[],n=!1;for(let r of e){if(n){t.push({kind:`positional`,value:r});continue}if(r===`--`){t.push({kind:`separator`}),n=!0;continue}if(r.startsWith(`--`)){let e=r.indexOf(`=`);e===-1?t.push({kind:`long-flag`,name:r.slice(2),value:void 0}):t.push({kind:`long-flag`,name:r.slice(2,e),value:r.slice(e+1)});continue}if(r.startsWith(`-`)&&r.length>1){t.push({kind:`short-flags`,chars:r.slice(1)});continue}t.push({kind:`positional`,value:r})}return t}function r(e,t){for(let n of e){if(n===`--`)return!1;if(n===t)return!0}return!1}function i(t){let n=new Map;for(let[r,i]of Object.entries(t)){n.set(r,[r,i]);for(let t of e(i,{includeHidden:!0}))n.set(t,[r,i])}return n}function a(e){return e.kind!==`boolean`}function o(e,n,r,i=`--${e}`){switch(r.kind){case`string`:return n;case`number`:{let r=Number(n);if(Number.isNaN(r))throw new t(`Invalid number value '${n}' for flag ${i}`,{code:`INVALID_VALUE`,details:{flag:e,input:i,value:n,expected:`number`}});return r}case`boolean`:if(n===`true`||n===`1`)return!0;if(n===`false`||n===`0`)return!1;throw new t(`Invalid boolean value '${n}' for flag ${i}. Use true/false or 1/0`,{code:`INVALID_VALUE`,details:{flag:e,input:i,value:n,expected:`boolean`}});case`enum`:{let a=r.enumValues;if(a===void 0)throw new t(`Enum flag --${e} is misconfigured: no allowed values declared`,{code:`INVALID_SCHEMA`,details:{flag:e,kind:`enum`,missing:`enumValues`}});if(!a.includes(n))throw new t(`Invalid value '${n}' for flag ${i}. Allowed: ${a.join(`, `)}`,{code:`INVALID_VALUE`,details:{flag:e,input:i,value:n,allowed:a}});return n}case`array`:return r.elementSchema?o(e,n,r.elementSchema):n;case`custom`:if(!r.parseFn)return n;try{return r.parseFn(n)}catch(r){throw r instanceof t?r:new t(`Failed to parse flag ${i}: ${r instanceof Error?r.message:String(r)}`,{code:`INVALID_VALUE`,details:{flag:e,input:i,value:n},cause:r})}}}function s(e,n,r){switch(r.kind){case`string`:return n;case`number`:{let r=Number(n);if(Number.isNaN(r))throw new t(`Invalid number value '${n}' for argument <${e}>`,{code:`INVALID_VALUE`,details:{arg:e,value:n,expected:`number`}});return r}case`enum`:{let i=r.enumValues;if(i===void 0)throw new t(`Enum argument <${e}> is misconfigured: no allowed values declared`,{code:`INVALID_SCHEMA`,details:{arg:e,kind:`enum`,missing:`enumValues`}});if(!i.includes(n))throw new t(`Invalid value '${n}' for argument <${e}>. Allowed: ${i.join(`, `)}`,{code:`INVALID_VALUE`,details:{arg:e,value:n,allowed:i}});return n}case`custom`:if(!r.parseFn)return n;try{return r.parseFn(n)}catch(r){throw r instanceof t?r:new t(`Failed to parse argument <${e}>: ${r instanceof Error?r.message:String(r)}`,{code:`INVALID_VALUE`,details:{arg:e,value:n},cause:r})}}}function c(e,t){let r=n(t),a=i(e.flags),o={},s=[],c=0;for(;c<r.length;){let e=r[c];if(e===void 0)break;if(e.kind===`separator`){c++;continue}if(e.kind===`positional`){s.push(e.value),c++;continue}if(e.kind===`long-flag`){c=l(e,r,c,a,o);continue}c=u(e,r,c,a,o)}return{flags:o,args:f(e.args,s)}}function l(e,n,r,i,s){let c=i.get(e.name);if(!c){let n=p(e.name,i);throw new t(`Unknown flag --${e.name}${n?`. Did you mean --${n}?`:``}`,{code:`UNKNOWN_FLAG`,details:{flag:e.name,...n?{suggestion:n}:{}},...n?{suggest:`--${n}`}:{}})}let[l,u]=c;if(!a(u))return e.value===void 0?s[l]=!0:s[l]=o(l,e.value,u,`--${e.name}`),r+1;if(e.value!==void 0)return d(s,l,u,e.value),r+1;let f=n[r+1];if(f?.kind!==`positional`)throw new t(`Flag --${e.name} requires a value`,{code:`MISSING_VALUE`,details:{flag:l,input:e.name,kind:u.kind}});return d(s,l,u,f.value,`--${e.name}`),r+2}function u(e,n,r,i,o){let{chars:s}=e,c=r+1;for(let e=0;e<s.length;e++){let r=s.charAt(e),l=i.get(r);if(!l)throw new t(`Unknown flag -${r}`,{code:`UNKNOWN_FLAG`,details:{flag:r}});let[u,f]=l;if(!a(f)){o[u]=!0;continue}if(e<s.length-1){d(o,u,f,s.slice(e+1),`-${r}`);break}let p=n[c];if(p?.kind!==`positional`)throw new t(`Flag -${r} requires a value`,{code:`MISSING_VALUE`,details:{flag:u,input:r,kind:f.kind}});d(o,u,f,p.value,`-${r}`),c++}return c}function d(e,t,n,r,i=`--${t}`){let a=o(t,r,n,i);if(n.kind===`array`){let n=e[t];Array.isArray(n)?n.push(a):e[t]=[a]}else e[t]=a}function f(e,n){let r={},i=0;for(let t of e){if(t.schema.variadic){let e=n.slice(i);r[t.name]=e.map(e=>s(t.name,e,t.schema)),i=n.length;break}let e=n[i];e!==void 0&&(r[t.name]=s(t.name,e,t.schema),i++)}if(i<n.length){let r=n.slice(i);throw new t(`Unexpected positional argument${r.length>1?`s`:``}: ${r.join(`, `)}`,{code:`UNEXPECTED_POSITIONAL`,details:{excess:r,expected:e.length}})}return r}function p(e,t){let n,r=1/0,i=Math.max(2,Math.floor(e.length/2));for(let a of t.keys()){let o=t.get(a);if(o===void 0)continue;let[s,c]=o,l=c.aliases.find(e=>e.name===a);if(a.length<2||a!==s&&l?.hidden)continue;let u=m(e,a);u<r&&u<=i&&(r=u,n=a)}return n}function m(e,t){if(e===t)return 0;if(e.length===0)return t.length;if(t.length===0)return e.length;let n=e.length<=t.length?e:t,r=e.length<=t.length?t:e,i=n.length,a=r.length,o=Array.from({length:i+1},(e,t)=>t);for(let e=1;e<=a;e++){let t=o[0]??0;o[0]=e;for(let a=1;a<=i;a++){let i=n.charAt(a-1)===r.charAt(e-1)?0:1,s=Math.min((o[a]??0)+1,(o[a-1]??0)+1,t+i);t=o[a]??0,o[a]=s}}return o[i]??0}export{i as buildFlagLookup,a as flagExpectsValue,r as includesBeforeSeparator,c as parse,n as tokenize};
1
+ import{describeNumberConstraintViolation as e,validateNumberConstraints as t}from"../schema/number-constraints.mjs";import{getFlagAliasNames as n}from"../schema/flag.mjs";import{ParseError as r}from"../errors/index.mjs";function i(e){let t=[],n=!1;for(let r of e){if(n){t.push({kind:`positional`,value:r});continue}if(r===`--`){t.push({kind:`separator`}),n=!0;continue}if(r.startsWith(`--`)){let e=r.indexOf(`=`);e===-1?t.push({kind:`long-flag`,name:r.slice(2),value:void 0}):t.push({kind:`long-flag`,name:r.slice(2,e),value:r.slice(e+1)});continue}if(r.startsWith(`-`)&&r.length>1){t.push({kind:`short-flags`,chars:r.slice(1)});continue}t.push({kind:`positional`,value:r})}return t}function a(e,t){for(let n of e){if(n===`--`)return!1;if(n===t)return!0}return!1}function o(e,t){let n=e.indexOf(`--`),r=n===-1?e:e.slice(0,n);if(!r.includes(t))return e;let i=r.filter(e=>e!==t);return n===-1?i:[...i,...e.slice(n)]}function s(e){let t=new Map;for(let[r,i]of Object.entries(e)){t.set(r,[r,i]);for(let e of n(i,{includeHidden:!0}))t.set(e,[r,i])}return t}function c(e){return e.kind!==`boolean`}function l(n,i,a,o=`--${n}`){switch(a.kind){case`string`:return i;case`number`:{let s=Number(i);if(Number.isNaN(s))throw new r(`Invalid number value '${i}' for flag ${o}`,{code:`INVALID_VALUE`,details:{flag:n,input:o,value:i,expected:`number`}});let c=t(s,a.numberConstraints);if(c!==void 0)throw new r(`Invalid number value '${i}' for flag ${o}: ${e(c)}`,{code:`INVALID_VALUE`,details:{flag:n,input:o,value:i,expected:`number`,constraint:c.kind,...`bound`in c?{bound:c.bound}:{}}});return s}case`boolean`:if(i===`true`||i===`1`)return!0;if(i===`false`||i===`0`)return!1;throw new r(`Invalid boolean value '${i}' for flag ${o}. Use true/false or 1/0`,{code:`INVALID_VALUE`,details:{flag:n,input:o,value:i,expected:`boolean`}});case`enum`:{let e=a.enumValues;if(e===void 0)throw new r(`Enum flag --${n} is misconfigured: no allowed values declared`,{code:`INVALID_SCHEMA`,details:{flag:n,kind:`enum`,missing:`enumValues`}});if(!e.includes(i))throw new r(`Invalid value '${i}' for flag ${o}. Allowed: ${e.join(`, `)}`,{code:`INVALID_VALUE`,details:{flag:n,input:o,value:i,allowed:e}});return i}case`array`:return a.elementSchema?l(n,i,a.elementSchema):i;case`custom`:if(!a.parseFn)return i;try{return a.parseFn(i)}catch(e){throw e instanceof r?e:new r(`Failed to parse flag ${o}: ${e instanceof Error?e.message:String(e)}`,{code:`INVALID_VALUE`,details:{flag:n,input:o,value:i},cause:e})}}}function u(n,i,a){switch(a.kind){case`string`:return i;case`number`:{let o=Number(i);if(Number.isNaN(o))throw new r(`Invalid number value '${i}' for argument <${n}>`,{code:`INVALID_VALUE`,details:{arg:n,value:i,expected:`number`}});let s=t(o,a.numberConstraints);if(s!==void 0)throw new r(`Invalid number value '${i}' for argument <${n}>: ${e(s)}`,{code:`INVALID_VALUE`,details:{arg:n,value:i,expected:`number`,constraint:s.kind,...`bound`in s?{bound:s.bound}:{}}});return o}case`enum`:{let e=a.enumValues;if(e===void 0)throw new r(`Enum argument <${n}> is misconfigured: no allowed values declared`,{code:`INVALID_SCHEMA`,details:{arg:n,kind:`enum`,missing:`enumValues`}});if(!e.includes(i))throw new r(`Invalid value '${i}' for argument <${n}>. Allowed: ${e.join(`, `)}`,{code:`INVALID_VALUE`,details:{arg:n,value:i,allowed:e}});return i}case`custom`:if(!a.parseFn)return i;try{return a.parseFn(i)}catch(e){throw e instanceof r?e:new r(`Failed to parse argument <${n}>: ${e instanceof Error?e.message:String(e)}`,{code:`INVALID_VALUE`,details:{arg:n,value:i},cause:e})}}}function d(e,t){let n=i(t),r=s(e.flags),a={},o=[],c=0;for(;c<n.length;){let e=n[c];if(e===void 0)break;if(e.kind===`separator`){c++;continue}if(e.kind===`positional`){o.push(e.value),c++;continue}if(e.kind===`long-flag`){c=f(e,n,c,r,a);continue}c=p(e,n,c,r,a)}return{flags:a,args:h(e.args,o)}}function f(e,t,n,i,a){let o=i.get(e.name);if(!o){let t=g(e.name,i);throw new r(`Unknown flag --${e.name}${t?`. Did you mean --${t}?`:``}`,{code:`UNKNOWN_FLAG`,details:{flag:e.name,...t?{suggestion:t}:{}},...t?{suggest:`--${t}`}:{}})}let[s,u]=o;if(!c(u))return e.value===void 0?a[s]=!0:a[s]=l(s,e.value,u,`--${e.name}`),n+1;if(e.value!==void 0)return m(a,s,u,e.value),n+1;let d=t[n+1];if(d?.kind!==`positional`)throw new r(`Flag --${e.name} requires a value`,{code:`MISSING_VALUE`,details:{flag:s,input:e.name,kind:u.kind}});return m(a,s,u,d.value,`--${e.name}`),n+2}function p(e,t,n,i,a){let{chars:o}=e,s=n+1;for(let e=0;e<o.length;e++){let n=o.charAt(e),l=i.get(n);if(!l)throw new r(`Unknown flag -${n}`,{code:`UNKNOWN_FLAG`,details:{flag:n}});let[u,d]=l;if(!c(d)){a[u]=!0;continue}if(e<o.length-1){m(a,u,d,o.slice(e+1),`-${n}`);break}let f=t[s];if(f?.kind!==`positional`)throw new r(`Flag -${n} requires a value`,{code:`MISSING_VALUE`,details:{flag:u,input:n,kind:d.kind}});m(a,u,d,f.value,`-${n}`),s++}return s}function m(e,t,n,r,i=`--${t}`){let a=l(t,r,n,i);if(n.kind===`array`){let n=e[t];Array.isArray(n)?n.push(a):e[t]=[a]}else e[t]=a}function h(e,t){let n={},i=0;for(let r of e){if(r.schema.variadic){let e=t.slice(i);n[r.name]=e.map(e=>u(r.name,e,r.schema)),i=t.length;break}let e=t[i];e!==void 0&&(n[r.name]=u(r.name,e,r.schema),i++)}if(i<t.length){let n=t.slice(i);throw new r(`Unexpected positional argument${n.length>1?`s`:``}: ${n.join(`, `)}`,{code:`UNEXPECTED_POSITIONAL`,details:{excess:n,expected:e.length}})}return n}function g(e,t){let n,r=1/0,i=Math.max(2,Math.floor(e.length/2));for(let a of t.keys()){let o=t.get(a);if(o===void 0)continue;let[s,c]=o,l=c.aliases.find(e=>e.name===a);if(a.length<2||a!==s&&l?.hidden)continue;let u=_(e,a);u<r&&u<=i&&(r=u,n=a)}return n}function _(e,t){if(e===t)return 0;if(e.length===0)return t.length;if(t.length===0)return e.length;let n=e.length<=t.length?e:t,r=e.length<=t.length?t:e,i=n.length,a=r.length,o=Array.from({length:i+1},(e,t)=>t);for(let e=1;e<=a;e++){let t=o[0]??0;o[0]=e;for(let a=1;a<=i;a++){let i=n.charAt(a-1)===r.charAt(e-1)?0:1,s=Math.min((o[a]??0)+1,(o[a-1]??0)+1,t+i);t=o[a]??0,o[a]=s}}return o[i]??0}export{s as buildFlagLookup,c as flagExpectsValue,a as includesBeforeSeparator,d as parse,o as stripBeforeSeparator,i as tokenize};
@@ -105,9 +105,11 @@ declare const PROMPT_CANCEL: unique symbol;
105
105
  * A queued answer consumed by {@link createTestPrompter}.
106
106
  *
107
107
  * The test prompter returns these values exactly as provided; it does not
108
- * coerce or validate them. The normal resolution pipeline performs any later
109
- * type coercion, so tests can supply values in the same shapes real prompts
110
- * would yield:
108
+ * coerce them. The one exception mirrors the terminal prompter: a string answer
109
+ * to an `input` prompt is run through the prompt's `validate` function, and a
110
+ * failing answer is rejected as a cancellation (see {@link createTestPrompter}).
111
+ * The normal resolution pipeline performs any later type coercion, so tests can
112
+ * supply values in the same shapes real prompts would yield:
111
113
  *
112
114
  * - `string` for `input` and `select`
113
115
  * - `boolean` for `confirm`
@@ -139,6 +141,12 @@ interface TestPrompterOptions {
139
141
  * Pass `PROMPT_CANCEL` as an answer to simulate the user cancelling
140
142
  * that prompt.
141
143
  *
144
+ * For `input` prompts that declare a `validate` function, a string answer is
145
+ * validated just as the terminal prompter does. An answer that fails validation
146
+ * is rejected as a cancellation (`{ answered: false }`) — mirroring the terminal
147
+ * prompter exhausting its retries — so prompt validation is integration-testable
148
+ * via {@linkcode runCommand} rather than silently accepted as the resolved value.
149
+ *
142
150
  * @param answers - Ordered queue of answers. Use `PROMPT_CANCEL` for
143
151
  * cancellation.
144
152
  * @param options - Controls behavior when the queue is exhausted.
@@ -1,6 +1,6 @@
1
- const e=Symbol.for(`dreamcli.prompt.cancel`);function t(t,n){let r=0;return{promptOne(){if(r>=t.length)return n?.onExhausted===`cancel`?Promise.resolve({answered:!1}):Promise.reject(Error(`Test prompter exhausted: expected at most ${t.length} prompts, got prompt #${r+1}`));let i=t[r];return r+=1,i===e?Promise.resolve({answered:!1}):Promise.resolve({answered:!0,value:i})}}}function n(e,t){return{promptOne(n){switch(n.kind){case`confirm`:return r(n,e,t);case`input`:return i(n,e,t);case`select`:return a(n,e,t);case`multiselect`:return o(n,e,t)}}}}async function r(e,t,n){let r=0;for(;r<10;){n(`${e.message} (Y/n) `);let i=await t();if(i===null)return{answered:!1};let a=i.trim().toLowerCase();if(a===``||a===`y`||a===`yes`)return{answered:!0,value:!0};if(a===`n`||a===`no`)return{answered:!0,value:!1};n(`Please answer y or n.
2
- `),r+=1}return n(`Too many invalid attempts.
3
- `),{answered:!1}}async function i(e,t,n){let r=0;for(;r<10;){let i=e.placeholder===void 0?``:` (${e.placeholder})`;n(`${e.message}${i}: `);let a=await t();if(a===null)return{answered:!1};let o=a.trim();if(e.validate!==void 0){let t=e.validate(o);if(t!==!0){n(`${t}\n`),r+=1;continue}}return{answered:!0,value:o}}return n(`Too many invalid attempts.
1
+ const e=Symbol.for(`dreamcli.prompt.cancel`);function t(t,n){let r=0;return{promptOne(i){if(r>=t.length)return n?.onExhausted===`cancel`?Promise.resolve({answered:!1}):Promise.reject(Error(`Test prompter exhausted: expected at most ${t.length} prompts, got prompt #${r+1}`));let a=t[r];return r+=1,a===e||i.kind===`input`&&i.validate!==void 0&&typeof a==`string`&&i.validate(a)!==!0?Promise.resolve({answered:!1}):Promise.resolve({answered:!0,value:a})}}}function n(e,t){return{promptOne(n){switch(n.kind){case`confirm`:return r(n,e,t);case`input`:return i(n,e,t);case`select`:return a(n,e,t);case`multiselect`:return o(n,e,t)}}}}async function r(e,t,n){let r=e.default??!0,i=0;for(;i<10;){let a=r?`(Y/n)`:`(y/N)`;n(`${e.message} ${a} `);let o=await t();if(o===null)return{answered:!1};let s=o.trim().toLowerCase();if(s===``)return{answered:!0,value:r};if(s===`y`||s===`yes`)return{answered:!0,value:!0};if(s===`n`||s===`no`)return{answered:!0,value:!1};n(`Please answer y or n.
2
+ `),i+=1}return n(`Too many invalid attempts.
3
+ `),{answered:!1}}async function i(e,t,n){let r=0,i=[];e.placeholder!==void 0&&i.push(e.placeholder),e.default!==void 0&&i.push(`default: ${e.default}`);let a=i.length>0?` (${i.join(`, `)})`:``;for(;r<10;){n(`${e.message}${a}: `);let i=await t();if(i===null)return{answered:!1};let o=i.trim();if(o===``)return e.default===void 0?{answered:!0,value:``}:{answered:!0,value:e.default};if(e.validate!==void 0){let t=e.validate(o);if(t!==!0){n(`${t}\n`),r+=1;continue}}return{answered:!0,value:o}}return n(`Too many invalid attempts.
4
4
  `),{answered:!1}}async function a(e,t,n){let r=0;for(;r<10;){n(`${e.message}\n`);for(let t=0;t<e.choices.length;t+=1){let r=e.choices[t];if(r===void 0)continue;let i=r.label??r.value,a=r.description===void 0?``:` - ${r.description}`;n(` ${t+1}) ${i}${a}\n`)}n(`Enter number: `);let i=await t();if(i===null)return{answered:!1};let a=Number(i.trim());if(Number.isNaN(a)||!Number.isInteger(a)||a<1||a>e.choices.length){n(`Please enter a number between 1 and ${e.choices.length}.\n`),r+=1;continue}let o=e.choices[a-1];if(o===void 0){r+=1;continue}return{answered:!0,value:o.value}}return n(`Too many invalid attempts.
5
5
  `),{answered:!1}}async function o(e,t,n){let r=0;for(;r<10;){n(`${e.message}\n`);for(let t=0;t<e.choices.length;t+=1){let r=e.choices[t];if(r===void 0)continue;let i=r.label??r.value,a=r.description===void 0?``:` - ${r.description}`;n(` ${t+1}) ${i}${a}\n`)}n(`Enter numbers separated by commas (e.g. 1,3${e.min===void 0?``:`, min: ${e.min}`}${e.max===void 0?``:`, max: ${e.max}`}): `);let i=await t();if(i===null)return{answered:!1};let a=i.trim();if(a===``){if(e.min!==void 0&&e.min>0){n(`Please select at least ${e.min}.\n`),r+=1;continue}return{answered:!0,value:[]}}let o=a.split(`,`).map(e=>e.trim()),s=[],c=!0;for(let t of o){let r=Number(t);if(Number.isNaN(r)||!Number.isInteger(r)||r<1||r>e.choices.length){n(`Invalid selection '${t}'. Use numbers between 1 and ${e.choices.length}.\n`),c=!1;break}s.push(r)}if(!c){r+=1;continue}let l=[...new Set(s)];if(e.min!==void 0&&l.length<e.min){n(`Please select at least ${e.min}.\n`),r+=1;continue}if(e.max!==void 0&&l.length>e.max){n(`Please select at most ${e.max}.\n`),r+=1;continue}return{answered:!0,value:l.map(t=>e.choices[t-1]?.value??``)}}return n(`Too many invalid attempts.
6
6
  `),{answered:!1}}function s(e,t){if(e.kind===`confirm`||e.kind===`input`)return e;let n=e.choices??t?.map(e=>({value:e}))??[];if(n.length===0)throw Error(`Prompt config (${e.kind}) requires choices but none were provided and no enum values are available`);let r=n;return e.kind===`select`?{kind:`select`,message:e.message,choices:r}:{kind:`multiselect`,message:e.message,choices:r,...e.min===void 0?{}:{min:e.min},...e.max===void 0?{}:{max:e.max}}}export{e as PROMPT_CANCEL,n as createTerminalPrompter,t as createTestPrompter,s as resolvePromptConfig};
@@ -1 +1 @@
1
- import{ValidationError as e}from"../errors/index.mjs";import{toSharedArgPropertySchema as t,toSharedFlagPropertySchema as n}from"./property.mjs";function r(e){switch(e.kind){case`env`:return`from env ${e.envVar}`;case`config`:return`from config ${e.configPath}`;case`prompt`:return`from prompt`}}function i(e){switch(e.kind){case`env`:return{envVar:e.envVar};case`config`:return{configPath:e.configPath};case`prompt`:return{source:`prompt`}}}function a(t,n,a,o,s,c,l,u){return{ok:!1,error:new e(`${c} ${r(n)} for flag --${t}`,{code:a,details:{flag:t,...i(n),value:s,expected:o,...u},suggest:l})}}function o(e,t,r,i){let c=n(i);if(c!==void 0)return s(e,t,r,c);switch(i.kind){case`boolean`:if(typeof r==`boolean`)return{ok:!0,value:r};if(typeof r==`string`){let e=r.toLowerCase();if(e===`true`||e===`1`||e===`yes`||t.kind===`prompt`&&e===`y`)return{ok:!0,value:!0};if(e===`false`||e===`0`||e===`no`||e===``||t.kind===`prompt`&&e===`n`)return{ok:!0,value:!1}}return a(e,t,`TYPE_MISMATCH`,`boolean`,r,typeof r==`string`?`Invalid boolean value '${r}'`:`Invalid boolean value`,t.kind===`env`?`Set ${t.envVar} to true/false, 1/0, or yes/no`:t.kind===`config`?`Set ${t.configPath} to true or false in your config`:`Answer yes or no for --${e}`);case`array`:if(Array.isArray(r)){if(i.elementSchema){let n=[];for(let a of r){let r=o(e,t,a,i.elementSchema);if(!r.ok)return r;n.push(r.value)}return{ok:!0,value:n}}return{ok:!0,value:r}}if(typeof r==`string`){if(r===``)return{ok:!0,value:[]};let n=r.split(`,`);if(i.elementSchema){let r=[];for(let a of n){let n=o(e,t,t.kind===`prompt`?a.trim():a,i.elementSchema);if(!n.ok)return n;r.push(n.value)}return{ok:!0,value:r}}return{ok:!0,value:t.kind===`prompt`?n.map(e=>e.trim()):n}}return a(e,t,`TYPE_MISMATCH`,`array`,r,`Invalid array value`,t.kind===`env`?`Set ${t.envVar} to comma-separated values`:t.kind===`config`?`Set ${t.configPath} to an array in your config`:`Provide valid values for --${e}`)}throw Error(`Unreachable flag coercion kind: ${i.kind}`)}function s(t,n,o,s){switch(s.kind){case`string`:return typeof o==`string`?{ok:!0,value:o}:n.kind===`prompt`||n.kind===`config`&&(typeof o==`number`||typeof o==`boolean`)?{ok:!0,value:String(o)}:a(t,n,`TYPE_MISMATCH`,`string`,o,`Invalid string value`,n.kind===`config`?`Set ${n.configPath} to a string in your config`:`Enter a valid string for --${t}`);case`number`:if(typeof o==`number`)return Number.isNaN(o)?a(t,n,`TYPE_MISMATCH`,`number`,o,`Invalid number value NaN`,n.kind===`env`?`Set ${n.envVar} to a valid number`:n.kind===`config`?`Set ${n.configPath} to a valid number in your config`:`Enter a valid number for --${t}`):{ok:!0,value:o};if(typeof o==`string`){let e=Number(o);if(!Number.isNaN(e))return{ok:!0,value:e}}return a(t,n,`TYPE_MISMATCH`,`number`,o,typeof o==`string`?`Invalid number value '${o}'`:`Invalid number value`,n.kind===`env`?`Set ${n.envVar} to a valid number`:n.kind===`config`?`Set ${n.configPath} to a valid number in your config`:`Enter a valid number for --${t}`);case`enum`:{let a=s.enumValues??[];return typeof o==`string`&&a.includes(o)?{ok:!0,value:o}:{ok:!1,error:new e(`Invalid value '${String(o)}' ${r(n)} for flag --${t}. Allowed: ${a.join(`, `)}`,{code:`INVALID_ENUM`,details:{flag:t,...i(n),value:o,allowed:a},suggest:n.kind===`env`?`Set ${n.envVar} to one of: ${a.join(`, `)}`:n.kind===`config`?`Set ${n.configPath} to one of: ${a.join(`, `)}`:`Select one of: ${a.join(`, `)}`})}}case`custom`:if(s.parseFn===void 0)return{ok:!0,value:o};try{return{ok:!0,value:s.parseFn(o)}}catch(r){let a=r instanceof Error?r.message:String(r);return{ok:!1,error:new e(`Failed to parse ${n.kind===`env`?`env ${n.envVar}`:n.kind===`config`?`config ${n.configPath}`:`prompt value`} for flag --${t}: ${a}`,{code:`TYPE_MISMATCH`,details:{flag:t,...i(n),value:o,expected:`custom`},suggest:n.kind===`env`?`Set ${n.envVar} to a valid value for --${t}`:n.kind===`config`?`Set ${n.configPath} to a valid value for --${t} in your config`:`Enter a valid value for --${t}`})}}}}function c(e){return e.kind===`env`?`from env ${e.envVar}`:`from stdin`}function l(e){return e.kind===`env`?{envVar:e.envVar}:{source:`stdin`}}function u(e,t,n){return t.kind===`env`?n===`number`?`Set ${t.envVar} to a valid number`:`Set ${t.envVar} to a valid value for <${e}>`:n===`number`?`Pipe a valid number to stdin for <${e}>`:`Pipe a valid value to stdin for <${e}>`}function d(e){return e.kind===`env`?{kind:`env`,envVar:e.envVar}:{kind:`prompt`}}function f(e,t,n,r){switch(n.kind){case`number`:return`Invalid number value '<redacted>' ${c(t)} for argument <${e}>`;case`enum`:{let n=Array.isArray(r.details?.allowed)?r.details.allowed.filter(e=>typeof e==`string`):[];return`Invalid value '<redacted>' ${c(t)} for argument <${e}>. Allowed: ${n.join(`, `)}`}case`custom`:{let n=/: ([^:]+)$/.exec(r.message)?.[1];return n===void 0?`Invalid value '<redacted>' ${c(t)} for argument <${e}>`:`Invalid value '<redacted>' ${c(t)} for argument <${e}>: ${n}`}case`string`:return`Invalid value '<redacted>' ${c(t)} for argument <${e}>`;default:return n.kind}}function p(e,t,n,r){return{arg:e,...l(t),...n.kind===`number`||n.kind===`custom`?{expected:n.kind}:{},...n.kind===`enum`&&Array.isArray(r.details?.allowed)?{allowed:r.details.allowed.filter(e=>typeof e==`string`)}:{}}}function m(e,t,n,r){if(n.kind===`number`||n.kind===`custom`)return u(e,t,n.kind);if(n.kind===`enum`){let e=(Array.isArray(r.details?.allowed)?r.details.allowed.filter(e=>typeof e==`string`):[]).join(`, `);return t.kind===`env`?`Set ${t.envVar} to one of: ${e}`:`Provide one of: ${e}`}}function h(n,r,i,a){let o=s(n,d(r),i,t(a));if(o.ok)return o;let c=m(n,r,a,o.error),l=c===void 0?{code:o.error.code,details:p(n,r,a,o.error)}:{code:o.error.code,details:p(n,r,a,o.error),suggest:c};return{ok:!1,error:new e(f(n,r,a,o.error),l)}}export{h as coerceArgStringValue,o as coerceValue};
1
+ import{describeNumberConstraintViolation as e,validateNumberConstraints as t}from"../schema/number-constraints.mjs";import{ValidationError as n}from"../errors/index.mjs";import{toSharedArgPropertySchema as r,toSharedFlagPropertySchema as i}from"./property.mjs";function a(e){switch(e.kind){case`env`:return`from env ${e.envVar}`;case`config`:return`from config ${e.configPath}`;case`prompt`:return`from prompt`}}function o(e){switch(e.kind){case`env`:return{envVar:e.envVar};case`config`:return{configPath:e.configPath};case`prompt`:return{source:`prompt`}}}function s(e,t,r,i,s,c,l,u){return{ok:!1,error:new n(`${c} ${a(t)} for flag --${e}`,{code:r,details:{flag:e,...o(t),value:s,expected:i,...u},suggest:l})}}function c(r,i,s,c,l){let u=t(c,l);if(u===void 0)return{ok:!0,value:c};let d=e(u);return{ok:!1,error:new n(`Invalid number value '${String(s)}' ${a(i)} for flag --${r}: ${d}`,{code:`CONSTRAINT_VIOLATED`,details:{flag:r,...o(i),value:s,expected:`number`,constraint:u.kind,...`bound`in u?{bound:u.bound}:{}},suggest:i.kind===`env`?`Set ${i.envVar} to a valid number`:i.kind===`config`?`Set ${i.configPath} to a valid number in your config`:`Enter a valid number for --${r}`})}}function l(e,t,n,r){let a=i(r);if(a!==void 0)return u(e,t,n,a);switch(r.kind){case`boolean`:if(typeof n==`boolean`)return{ok:!0,value:n};if(typeof n==`string`){let e=n.toLowerCase();if(e===`true`||e===`1`||e===`yes`||t.kind===`prompt`&&e===`y`)return{ok:!0,value:!0};if(e===`false`||e===`0`||e===`no`||e===``||t.kind===`prompt`&&e===`n`)return{ok:!0,value:!1}}return s(e,t,`TYPE_MISMATCH`,`boolean`,n,typeof n==`string`?`Invalid boolean value '${n}'`:`Invalid boolean value`,t.kind===`env`?`Set ${t.envVar} to true/false, 1/0, or yes/no`:t.kind===`config`?`Set ${t.configPath} to true or false in your config`:`Answer yes or no for --${e}`);case`array`:if(Array.isArray(n)){if(r.elementSchema){let i=[];for(let a of n){let n=l(e,t,a,r.elementSchema);if(!n.ok)return n;i.push(n.value)}return{ok:!0,value:i}}return{ok:!0,value:n}}if(typeof n==`string`){if(n===``)return{ok:!0,value:[]};let i=n.split(`,`);if(r.elementSchema){let n=[];for(let a of i){let i=l(e,t,t.kind===`prompt`?a.trim():a,r.elementSchema);if(!i.ok)return i;n.push(i.value)}return{ok:!0,value:n}}return{ok:!0,value:t.kind===`prompt`?i.map(e=>e.trim()):i}}return s(e,t,`TYPE_MISMATCH`,`array`,n,`Invalid array value`,t.kind===`env`?`Set ${t.envVar} to comma-separated values`:t.kind===`config`?`Set ${t.configPath} to an array in your config`:`Provide valid values for --${e}`)}throw Error(`Unreachable flag coercion kind: ${r.kind}`)}function u(e,t,r,i){switch(i.kind){case`string`:return typeof r==`string`?{ok:!0,value:r}:t.kind===`prompt`||t.kind===`config`&&(typeof r==`number`||typeof r==`boolean`)?{ok:!0,value:String(r)}:s(e,t,`TYPE_MISMATCH`,`string`,r,`Invalid string value`,t.kind===`config`?`Set ${t.configPath} to a string in your config`:`Enter a valid string for --${e}`);case`number`:if(typeof r==`number`)return Number.isNaN(r)?s(e,t,`TYPE_MISMATCH`,`number`,r,`Invalid number value NaN`,t.kind===`env`?`Set ${t.envVar} to a valid number`:t.kind===`config`?`Set ${t.configPath} to a valid number in your config`:`Enter a valid number for --${e}`):c(e,t,r,r,i.numberConstraints);if(typeof r==`string`){let n=Number(r);if(!Number.isNaN(n))return c(e,t,r,n,i.numberConstraints)}return s(e,t,`TYPE_MISMATCH`,`number`,r,typeof r==`string`?`Invalid number value '${r}'`:`Invalid number value`,t.kind===`env`?`Set ${t.envVar} to a valid number`:t.kind===`config`?`Set ${t.configPath} to a valid number in your config`:`Enter a valid number for --${e}`);case`enum`:{let s=i.enumValues??[];return typeof r==`string`&&s.includes(r)?{ok:!0,value:r}:{ok:!1,error:new n(`Invalid value '${String(r)}' ${a(t)} for flag --${e}. Allowed: ${s.join(`, `)}`,{code:`INVALID_ENUM`,details:{flag:e,...o(t),value:r,allowed:s},suggest:t.kind===`env`?`Set ${t.envVar} to one of: ${s.join(`, `)}`:t.kind===`config`?`Set ${t.configPath} to one of: ${s.join(`, `)}`:`Select one of: ${s.join(`, `)}`})}}case`custom`:if(i.parseFn===void 0)return{ok:!0,value:r};try{return{ok:!0,value:i.parseFn(r)}}catch(i){let a=i instanceof Error?i.message:String(i);return{ok:!1,error:new n(`Failed to parse ${t.kind===`env`?`env ${t.envVar}`:t.kind===`config`?`config ${t.configPath}`:`prompt value`} for flag --${e}: ${a}`,{code:`TYPE_MISMATCH`,details:{flag:e,...o(t),value:r,expected:`custom`},suggest:t.kind===`env`?`Set ${t.envVar} to a valid value for --${e}`:t.kind===`config`?`Set ${t.configPath} to a valid value for --${e} in your config`:`Enter a valid value for --${e}`})}}}}function d(e){return e.kind===`env`?`from env ${e.envVar}`:`from stdin`}function f(e){return e.kind===`env`?{envVar:e.envVar}:{source:`stdin`}}function p(e,t,n){return t.kind===`env`?n===`number`?`Set ${t.envVar} to a valid number`:`Set ${t.envVar} to a valid value for <${e}>`:n===`number`?`Pipe a valid number to stdin for <${e}>`:`Pipe a valid value to stdin for <${e}>`}function m(e){return e.kind===`env`?{kind:`env`,envVar:e.envVar}:{kind:`prompt`}}function h(e,t,n,r){switch(n.kind){case`number`:{let n=`Invalid number value '<redacted>' ${d(t)} for argument <${e}>`;if(r.code!==`CONSTRAINT_VIOLATED`)return n;let i=/: ([^:]+)$/.exec(r.message)?.[1];return i===void 0?n:`${n}: ${i}`}case`enum`:{let n=Array.isArray(r.details?.allowed)?r.details.allowed.filter(e=>typeof e==`string`):[];return`Invalid value '<redacted>' ${d(t)} for argument <${e}>. Allowed: ${n.join(`, `)}`}case`custom`:{let n=/: ([^:]+)$/.exec(r.message)?.[1];return n===void 0?`Invalid value '<redacted>' ${d(t)} for argument <${e}>`:`Invalid value '<redacted>' ${d(t)} for argument <${e}>: ${n}`}case`string`:return`Invalid value '<redacted>' ${d(t)} for argument <${e}>`;default:return n.kind}}function g(e,t,n,r){return{arg:e,...f(t),...n.kind===`number`||n.kind===`custom`?{expected:n.kind}:{},...n.kind===`number`&&typeof r.details?.constraint==`string`?{constraint:r.details.constraint}:{},...n.kind===`number`&&typeof r.details?.bound==`number`?{bound:r.details.bound}:{},...n.kind===`enum`&&Array.isArray(r.details?.allowed)?{allowed:r.details.allowed.filter(e=>typeof e==`string`)}:{}}}function _(e,t,n,r){if(n.kind===`number`||n.kind===`custom`)return p(e,t,n.kind);if(n.kind===`enum`){let e=(Array.isArray(r.details?.allowed)?r.details.allowed.filter(e=>typeof e==`string`):[]).join(`, `);return t.kind===`env`?`Set ${t.envVar} to one of: ${e}`:`Provide one of: ${e}`}}function v(e,t,i,a){let o=u(e,m(t),i,r(a));if(o.ok)return o;let s=_(e,t,a,o.error),c=s===void 0?{code:o.error.code,details:g(e,t,a,o.error)}:{code:o.error.code,details:g(e,t,a,o.error),suggest:s};return{ok:!1,error:new n(h(e,t,a,o.error),c)}}export{v as coerceArgStringValue,l as coerceValue};