@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{ValidationError as e}from"../errors/index.mjs";import{resolvePromptConfig as t}from"../prompt/index.mjs";import{coerceValue as n}from"./coerce.mjs";import{isNonEmpty as r,throwAggregatedErrors as i}from"./errors.mjs";import{resolveConfigPath as a}from"./config.mjs";async function o(t,o,s,c,d,f,p){let m={},h=[],g=new Set;for(let[e,r]of Object.entries(t)){let t=Object.hasOwn(o,e),i=o[e];if(t&&i!==void 0){r.deprecated!==void 0&&p.push({kind:`flag`,name:e,message:r.deprecated}),m[e]=i;continue}if(r.envVar!==void 0){let t=s[r.envVar];if(t!==void 0){let i=n(e,{kind:`env`,envVar:r.envVar},t,r);if(i.ok){r.deprecated!==void 0&&p.push({kind:`flag`,name:e,message:r.deprecated}),m[e]=i.value;continue}h.push(i.error),g.add(e);continue}}if(r.configPath!==void 0){let t=a(c,r.configPath);if(t!==void 0){let i=n(e,{kind:`config`,configPath:r.configPath},t,r);if(i.ok){r.deprecated!==void 0&&p.push({kind:`flag`,name:e,message:r.deprecated}),m[e]=i.value;continue}h.push(i.error),g.add(e)}}}let _=f===void 0?void 0:f({flags:m});for(let[n,r]of Object.entries(t)){if(Object.hasOwn(m,n)||g.has(n))continue;let t=_?.[n],i;if(i=t!=null&&t!==!1&&t!==0&&t!==``?t:t===!1?void 0:r.prompt,i!==void 0&&d!==void 0){let e=await l(n,r,i,d);if(e.ok){r.deprecated!==void 0&&p.push({kind:`flag`,name:n,message:r.deprecated}),m[n]=e.value;continue}if(e.error!==void 0){h.push(e.error);continue}}if(r.defaultValue!==void 0){m[n]=r.defaultValue;continue}if(r.kind===`array`&&r.presence!==`required`){m[n]=[];continue}if(r.presence===`required`){let t={flag:n,kind:r.kind};r.envVar!==void 0&&(t.envVar=r.envVar),r.configPath!==void 0&&(t.configPath=r.configPath),h.push(new e(`Missing required flag --${n}`,{code:`REQUIRED_FLAG`,details:t,suggest:u(n,r)}));continue}m[n]=void 0}return r(h)&&i(h),m}const s={boolean:[`confirm`],string:[`input`,`select`],number:[`input`],enum:[`select`,`input`],array:[`multiselect`],custom:[`input`,`select`,`confirm`,`multiselect`]};function c(t,n,r){let i=s[n];if(!i.includes(r))return new e(`Prompt kind '${r}' is not compatible with ${n} flag --${t}. Use '${i[0]}' instead`,{code:`CONSTRAINT_VIOLATED`,details:{flag:t,flagKind:n,promptKind:r,allowed:i},suggest:`Change the prompt to { kind: '${i[0]}' } for --${t}`})}async function l(e,r,i,a){let o=c(e,r.kind,i.kind);if(o!==void 0)return{ok:!1,error:o};let s=t(i,r.enumValues),l=await a.promptOne(s);return l.answered?n(e,{kind:`prompt`},l.value,r):{ok:!1,error:void 0}}function u(e,t){let n=[];if(n.push(`Provide --${e}${t.kind===`boolean`?``:` <value>`}`),t.envVar!==void 0&&n.push(`set ${t.envVar}`),t.configPath!==void 0&&n.push(`add ${t.configPath} to config`),n.length<=1)return n.join(``);let r=n.slice(0,-1),i=n.slice(-1).join(``);return n.length===2?`${r.join(``)} or ${i}`:`${r.join(`, `)}, or ${i}`}export{o as resolveFlags};
1
+ import{ValidationError as e}from"../errors/index.mjs";import{resolvePromptConfig as t}from"../prompt/index.mjs";import{coerceValue as n}from"./coerce.mjs";import{isNonEmpty as r,throwAggregatedErrors as i}from"./errors.mjs";import{resolveConfigPath as a}from"./config.mjs";async function o(t,o,s,c,d,f,p){let m={},h=[],g=new Set;for(let[e,r]of Object.entries(t)){let t=Object.hasOwn(o,e),i=o[e];if(t&&i!==void 0){r.deprecated!==void 0&&p.push({kind:`flag`,name:e,message:r.deprecated}),m[e]=i;continue}if(r.envVar!==void 0){let t=s[r.envVar];if(t!==void 0){let i=n(e,{kind:`env`,envVar:r.envVar},t,r);if(i.ok){r.deprecated!==void 0&&p.push({kind:`flag`,name:e,message:r.deprecated}),m[e]=i.value;continue}h.push(i.error),g.add(e);continue}}if(r.configPath!==void 0){let t=a(c,r.configPath);if(t!==void 0){let i=n(e,{kind:`config`,configPath:r.configPath},t,r);if(i.ok){r.deprecated!==void 0&&p.push({kind:`flag`,name:e,message:r.deprecated}),m[e]=i.value;continue}h.push(i.error),g.add(e)}}}let _=f===void 0?void 0:f({flags:m});for(let[n,r]of Object.entries(t)){if(Object.hasOwn(m,n)||g.has(n))continue;let t=_?.[n],i;if(i=t!=null&&t!==!1&&t!==0&&t!==``?t:t===!1?void 0:r.prompt,i!==void 0&&d!==void 0){let e=await l(n,r,i,d);if(e.ok){r.deprecated!==void 0&&p.push({kind:`flag`,name:n,message:r.deprecated}),m[n]=e.value;continue}if(e.error!==void 0){h.push(e.error);continue}}if(r.defaultValue!==void 0){m[n]=r.defaultValue;continue}if(r.kind===`array`&&r.presence!==`required`){m[n]=[];continue}if(r.presence===`required`){let t={flag:n,kind:r.kind};r.envVar!==void 0&&(t.envVar=r.envVar),r.configPath!==void 0&&(t.configPath=r.configPath),h.push(new e(`Missing required flag --${n}`,{code:`REQUIRED_FLAG`,details:t,suggest:u(n,r)}));continue}m[n]=void 0}return r(h)&&i(h),m}const s={boolean:[`confirm`],string:[`input`,`select`],number:[`input`],enum:[`select`,`input`],array:[`multiselect`],custom:[`input`,`select`,`confirm`,`multiselect`]};function c(t,n,r){let i=s[n];if(!i.includes(r))return new e(`Prompt kind '${r}' is not compatible with ${n} flag --${t}. Use '${i[0]}' instead`,{code:`CONSTRAINT_VIOLATED`,details:{flag:t,flagKind:n,promptKind:r,allowed:i},suggest:`Change the prompt to { kind: '${i[0]}' } for --${t}`})}async function l(e,r,i,a){let o=c(e,r.kind,i.kind);if(o!==void 0)return{ok:!1,error:o};let s=t(i,r.enumValues),l=await a.promptOne(s);return!l.answered||i.kind===`input`&&i.default===void 0&&typeof l.value==`string`&&l.value.trim()===``?{ok:!1,error:void 0}:n(e,{kind:`prompt`},l.value,r)}function u(e,t){let n=[];if(n.push(`Provide --${e}${t.kind===`boolean`?``:` <value>`}`),t.envVar!==void 0&&n.push(`set ${t.envVar}`),t.configPath!==void 0&&n.push(`add ${t.configPath} to config`),n.length<=1)return n.join(``);let r=n.slice(0,-1),i=n.slice(-1).join(``);return n.length===2?`${r.join(``)} or ${i}`:`${r.join(`, `)}, or ${i}`}export{o as resolveFlags};
@@ -1,3 +1,4 @@
1
+ import { NumberConstraints } from "../schema/number-constraints.mjs";
1
2
  import { ArgSchema } from "../schema/arg.mjs";
2
3
  import { FlagSchema } from "../schema/flag.mjs";
3
4
 
@@ -11,6 +12,7 @@ type SharedPropertySchema = {
11
12
  readonly kind: 'string';
12
13
  } | {
13
14
  readonly kind: 'number';
15
+ readonly numberConstraints: NumberConstraints | undefined;
14
16
  } | {
15
17
  readonly kind: 'enum';
16
18
  readonly enumValues: readonly string[] | undefined;
@@ -1 +1 @@
1
- function e(e){switch(e.kind){case`string`:return{kind:`string`};case`number`:return{kind:`number`};case`enum`:return{kind:`enum`,enumValues:e.enumValues};case`custom`:return e.parseFn===void 0?{kind:`custom`}:{kind:`custom`,parseFn:e.parseFn};case`boolean`:case`array`:return}}function t(e){switch(e.kind){case`string`:return{kind:`string`};case`number`:return{kind:`number`};case`enum`:return{kind:`enum`,enumValues:e.enumValues};case`custom`:{if(e.parseFn===void 0)return{kind:`custom`};let t=e.parseFn;return{kind:`custom`,parseFn:e=>t(typeof e==`string`?e:String(e))}}}}export{t as toSharedArgPropertySchema,e as toSharedFlagPropertySchema};
1
+ function e(e){switch(e.kind){case`string`:return{kind:`string`};case`number`:return{kind:`number`,numberConstraints:e.numberConstraints};case`enum`:return{kind:`enum`,enumValues:e.enumValues};case`custom`:return e.parseFn===void 0?{kind:`custom`}:{kind:`custom`,parseFn:e.parseFn};case`boolean`:case`array`:return}}function t(e){switch(e.kind){case`string`:return{kind:`string`};case`number`:return{kind:`number`,numberConstraints:e.numberConstraints};case`enum`:return{kind:`enum`,enumValues:e.enumValues};case`custom`:{if(e.parseFn===void 0)return{kind:`custom`};let t=e.parseFn;return{kind:`custom`,parseFn:e=>t(typeof e==`string`?e:String(e))}}}}export{t as toSharedArgPropertySchema,e as toSharedFlagPropertySchema};
@@ -1,13 +1,6 @@
1
+ import { NumberConstraints } from "./number-constraints.mjs";
2
+
1
3
  //#region src/core/schema/arg.d.ts
2
- /**
3
- * Positional argument schema builder with full type inference.
4
- *
5
- * Each factory (`arg.string()`, `arg.number()`, `arg.enum()`, `arg.custom()`) returns an
6
- * immutable {@linkcode ArgBuilder} whose generic parameter tracks the value type,
7
- * presence state, and variadic flag through the fluent chain.
8
- *
9
- * @module dreamcli/core/schema/arg
10
- */
11
4
  /** All arg presence states as a runtime array. */
12
5
  declare const ARG_PRESENCES: readonly ['required', 'optional', 'defaulted'];
13
6
  /**
@@ -29,6 +22,8 @@ interface ArgConfig {
29
22
  readonly presence: ArgPresence;
30
23
  /** Whether this arg consumes remaining positionals. */
31
24
  readonly variadic: boolean;
25
+ /** The runtime kind discriminator, mirroring {@link ArgKind}. */
26
+ readonly argKind: ArgKind;
32
27
  }
33
28
  /**
34
29
  * Advanced type helper used by {@linkcode ArgBuilder} modifiers to replace presence.
@@ -38,6 +33,7 @@ type WithArgPresence<C extends ArgConfig, P extends ArgPresence> = {
38
33
  readonly valueType: C['valueType'];
39
34
  readonly presence: P;
40
35
  readonly variadic: C['variadic'];
36
+ readonly argKind: C['argKind'];
41
37
  };
42
38
  /**
43
39
  * Advanced type helper used by {@linkcode ArgBuilder.variadic | ArgBuilder.variadic()}.
@@ -47,6 +43,7 @@ type WithVariadic<C extends ArgConfig> = {
47
43
  readonly valueType: C['valueType'];
48
44
  readonly presence: C['presence'];
49
45
  readonly variadic: true;
46
+ readonly argKind: C['argKind'];
50
47
  };
51
48
  /**
52
49
  * Compute the final value type from config — this is what handlers receive.
@@ -102,6 +99,13 @@ interface ArgSchema {
102
99
  readonly envVar: string | undefined;
103
100
  /** Allowed literal values when `kind === 'enum'`. */
104
101
  readonly enumValues: readonly string[] | undefined;
102
+ /**
103
+ * Numeric constraints when `kind === 'number'` (`undefined` otherwise).
104
+ *
105
+ * Enforced at the parse and resolution boundaries. `finite` defaults to
106
+ * `true`, so `Infinity` is rejected even when no constraints object is set.
107
+ */
108
+ readonly numberConstraints: NumberConstraints | undefined;
105
109
  /** Custom parse function (only when `kind === 'custom'`). */
106
110
  readonly parseFn: ArgParseFn<unknown> | undefined;
107
111
  /**
@@ -376,6 +380,71 @@ declare class ArgBuilder<C extends ArgConfig> {
376
380
  * ```
377
381
  */
378
382
  deprecated(message?: string): ArgBuilder<C>;
383
+ /**
384
+ * Require an integer value. Composes with other numeric constraints.
385
+ *
386
+ * @param value - Whether to require an integer.
387
+ * @defaultValue `true`
388
+ * @returns The builder (for chaining).
389
+ *
390
+ * @example
391
+ * ```ts
392
+ * arg.number().int() // rejects 3.7, accepts 3
393
+ * arg.number({ int: true }).int(false) // re-allows non-integers
394
+ * ```
395
+ */
396
+ int(this: ArgBuilder<C & {
397
+ readonly argKind: 'number';
398
+ }>, value?: boolean): ArgBuilder<C>;
399
+ /**
400
+ * Set an inclusive lower bound. Composes with other numeric constraints;
401
+ * a later call overrides an earlier `min` (including one from the options
402
+ * object).
403
+ *
404
+ * @param value - Inclusive minimum.
405
+ * @returns The builder (for chaining).
406
+ *
407
+ * @example
408
+ * ```ts
409
+ * arg.number().min(0) // rejects -1, accepts 0
410
+ * arg.number({ min: 0 }).min(5) // effective min is 5
411
+ * ```
412
+ */
413
+ min(this: ArgBuilder<C & {
414
+ readonly argKind: 'number';
415
+ }>, value: number): ArgBuilder<C>;
416
+ /**
417
+ * Set an inclusive upper bound. Composes with other numeric constraints;
418
+ * a later call overrides an earlier `max`.
419
+ *
420
+ * @param value - Inclusive maximum.
421
+ * @returns The builder (for chaining).
422
+ *
423
+ * @example
424
+ * ```ts
425
+ * arg.number().max(100) // rejects 101, accepts 100
426
+ * ```
427
+ */
428
+ max(this: ArgBuilder<C & {
429
+ readonly argKind: 'number';
430
+ }>, value: number): ArgBuilder<C>;
431
+ /**
432
+ * Require (or, with `false`, allow) a finite value. Finiteness is enforced
433
+ * by default, so this is mainly used as `.finite(false)` to re-allow
434
+ * `Infinity` / `-Infinity`.
435
+ *
436
+ * @param allow - Whether to require a finite value.
437
+ * @defaultValue `true`
438
+ * @returns The builder (for chaining).
439
+ *
440
+ * @example
441
+ * ```ts
442
+ * arg.number().finite(false) // accepts Infinity
443
+ * ```
444
+ */
445
+ finite(this: ArgBuilder<C & {
446
+ readonly argKind: 'number';
447
+ }>, allow?: boolean): ArgBuilder<C>;
379
448
  }
380
449
  /**
381
450
  * Arg factory functions — the public API for creating positional arguments.
@@ -439,6 +508,7 @@ interface ArgFactory {
439
508
  readonly valueType: string;
440
509
  readonly presence: 'required';
441
510
  readonly variadic: false;
511
+ readonly argKind: 'string';
442
512
  }>;
443
513
  /**
444
514
  * Number-valued positional argument. Required by default.
@@ -460,12 +530,20 @@ interface ArgFactory {
460
530
  * // $ mycli serve → 3000
461
531
  * ```
462
532
  *
533
+ * Constraints are enforced at the parse and resolution boundaries and also
534
+ * compose via chained methods (`.int()`, `.min()`, `.max()`, `.finite()`),
535
+ * which override values set here. The resolved value type stays `number`.
536
+ *
537
+ * @param constraints - Optional numeric constraints. `finite` defaults to
538
+ * `true`, so `Infinity` / `-Infinity` are rejected unless `finite: false`.
539
+ * @defaultValue `undefined` (finite-only, no bounds, non-integer allowed)
463
540
  * @returns A required number {@link ArgBuilder}.
464
541
  */
465
- number(): ArgBuilder<{
542
+ number(constraints?: NumberConstraints): ArgBuilder<{
466
543
  readonly valueType: number;
467
544
  readonly presence: 'required';
468
545
  readonly variadic: false;
546
+ readonly argKind: 'number';
469
547
  }>;
470
548
  /**
471
549
  * Enum-valued positional argument. Required by default.
@@ -494,6 +572,7 @@ interface ArgFactory {
494
572
  readonly valueType: T[number];
495
573
  readonly presence: 'required';
496
574
  readonly variadic: false;
575
+ readonly argKind: 'enum';
497
576
  }>;
498
577
  /**
499
578
  * Custom-parsed positional argument. Required by default.
@@ -524,6 +603,7 @@ interface ArgFactory {
524
603
  readonly valueType: T;
525
604
  readonly presence: 'required';
526
605
  readonly variadic: false;
606
+ readonly argKind: 'custom';
527
607
  }>;
528
608
  }
529
609
  /**
@@ -1 +1 @@
1
- function e(e,t){return{kind:e,presence:`required`,variadic:!1,stdinMode:!1,defaultValue:void 0,description:void 0,envVar:void 0,enumValues:void 0,parseFn:void 0,deprecated:void 0,...t}}var t=class e{schema;constructor(e){this.schema=e}required(){return new e({...this.schema,presence:`required`})}optional(){return new e({...this.schema,presence:`optional`})}default(t){return new e({...this.schema,presence:`defaulted`,defaultValue:t})}variadic(){return new e({...this.schema,variadic:!0})}stdin(){return new e({...this.schema,stdinMode:!0})}env(t){return new e({...this.schema,envVar:t})}describe(t){return new e({...this.schema,description:t})}deprecated(t){return new e({...this.schema,deprecated:t??!0})}};const n={string(){return new t(e(`string`))},number(){return new t(e(`number`))},enum(n){return new t(e(`enum`,{enumValues:n}))},custom(n){return new t(e(`custom`,{parseFn:n}))}};export{t as ArgBuilder,n as arg,e as createArgSchema};
1
+ import{assertNumberConstraints as e}from"./number-constraints.mjs";function t(e,t){return{kind:e,presence:`required`,variadic:!1,stdinMode:!1,defaultValue:void 0,description:void 0,envVar:void 0,enumValues:void 0,numberConstraints:void 0,parseFn:void 0,deprecated:void 0,...t}}var n=class t{schema;constructor(e){this.schema=e}required(){return new t({...this.schema,presence:`required`})}optional(){return new t({...this.schema,presence:`optional`})}default(e){return new t({...this.schema,presence:`defaulted`,defaultValue:e})}variadic(){return new t({...this.schema,variadic:!0})}stdin(){return new t({...this.schema,stdinMode:!0})}env(e){return new t({...this.schema,envVar:e})}describe(e){return new t({...this.schema,description:e})}deprecated(e){return new t({...this.schema,deprecated:e??!0})}int(e=!0){return new t({...this.schema,numberConstraints:{...this.schema.numberConstraints,int:e}})}min(n){let r={...this.schema.numberConstraints,min:n};return e(r),new t({...this.schema,numberConstraints:r})}max(n){let r={...this.schema.numberConstraints,max:n};return e(r),new t({...this.schema,numberConstraints:r})}finite(e=!0){return new t({...this.schema,numberConstraints:{...this.schema.numberConstraints,finite:e}})}};const r={string(){return new n(t(`string`))},number(r){return r!==void 0&&e(r),new n(t(`number`,r===void 0?{}:{numberConstraints:r}))},enum(e){return new n(t(`enum`,{enumValues:e}))},custom(e){return new n(t(`custom`,{parseFn:e}))}};export{n as ArgBuilder,r as arg,t as createArgSchema};
@@ -775,7 +775,9 @@ declare class CommandBuilder<F extends Record<string, FlagBuilder<FlagConfig>> =
775
775
  * The builder controls the flag's type, presence, aliases, env/config
776
776
  * bindings, and description. See {@link FlagBuilder} for available modifiers.
777
777
  *
778
- * @param name - Flag name (used as `--name` on CLI and `flags.*` in handler).
778
+ * @param name - Flag name: the `--name` CLI token and the matching key on `flags`
779
+ * in the handler. The name is preserved as-is (no camelCasing); read non-identifier
780
+ * names such as `'dry-run'` with bracket access (`flags['dry-run']`).
779
781
  * @param builder - Configured {@linkcode FlagBuilder} from {@linkcode flag | flag.string()},
780
782
  * `flag.boolean()`, `flag.number()`, `flag.enum()`, `flag.array()`, or `flag.custom()`.
781
783
  *
@@ -1,3 +1,4 @@
1
+ import { NumberConstraints } from "./number-constraints.mjs";
1
2
  import { ConfirmPromptConfig, InputPromptConfig, MultiselectPromptConfig, PROMPT_KINDS, PromptConfig, PromptConfigBase, PromptKind, PromptResult, SelectChoice, SelectPromptConfig } from "./prompt.mjs";
2
3
 
3
4
  //#region src/core/schema/flag.d.ts
@@ -123,6 +124,13 @@ interface FlagSchema {
123
124
  readonly description: string | undefined;
124
125
  /** Allowed literal values when `kind === 'enum'`. */
125
126
  readonly enumValues: readonly string[] | undefined;
127
+ /**
128
+ * Numeric constraints when `kind === 'number'` (`undefined` otherwise).
129
+ *
130
+ * Enforced at the parse and resolution boundaries. `finite` defaults to
131
+ * `true`, so `Infinity` is rejected even when no constraints object is set.
132
+ */
133
+ readonly numberConstraints: NumberConstraints | undefined;
126
134
  /** Element schema when `kind === 'array'`. */
127
135
  readonly elementSchema: FlagSchema | undefined;
128
136
  /** Interactive prompt configuration for v0.3+ resolution. */
@@ -397,6 +405,71 @@ declare class FlagBuilder<C extends FlagConfig> {
397
405
  * ```
398
406
  */
399
407
  propagate(): FlagBuilder<C>;
408
+ /**
409
+ * Require an integer value. Composes with other numeric constraints.
410
+ *
411
+ * @param value - Whether to require an integer.
412
+ * @defaultValue `true`
413
+ * @returns The builder (for chaining).
414
+ *
415
+ * @example
416
+ * ```ts
417
+ * flag.number().int() // rejects 3.7, accepts 3
418
+ * flag.number({ int: true }).int(false) // re-allows non-integers
419
+ * ```
420
+ */
421
+ int(this: FlagBuilder<C & {
422
+ readonly flagKind: 'number';
423
+ }>, value?: boolean): FlagBuilder<C>;
424
+ /**
425
+ * Set an inclusive lower bound. Composes with other numeric constraints;
426
+ * a later call overrides an earlier `min` (including one from the options
427
+ * object).
428
+ *
429
+ * @param value - Inclusive minimum.
430
+ * @returns The builder (for chaining).
431
+ *
432
+ * @example
433
+ * ```ts
434
+ * flag.number().min(0) // rejects -1, accepts 0
435
+ * flag.number({ min: 0 }).min(5) // effective min is 5
436
+ * ```
437
+ */
438
+ min(this: FlagBuilder<C & {
439
+ readonly flagKind: 'number';
440
+ }>, value: number): FlagBuilder<C>;
441
+ /**
442
+ * Set an inclusive upper bound. Composes with other numeric constraints;
443
+ * a later call overrides an earlier `max`.
444
+ *
445
+ * @param value - Inclusive maximum.
446
+ * @returns The builder (for chaining).
447
+ *
448
+ * @example
449
+ * ```ts
450
+ * flag.number().max(100) // rejects 101, accepts 100
451
+ * ```
452
+ */
453
+ max(this: FlagBuilder<C & {
454
+ readonly flagKind: 'number';
455
+ }>, value: number): FlagBuilder<C>;
456
+ /**
457
+ * Require (or, with `false`, allow) a finite value. Finiteness is enforced
458
+ * by default, so this is mainly used as `.finite(false)` to re-allow
459
+ * `Infinity` / `-Infinity`.
460
+ *
461
+ * @param allow - Whether to require a finite value.
462
+ * @defaultValue `true`
463
+ * @returns The builder (for chaining).
464
+ *
465
+ * @example
466
+ * ```ts
467
+ * flag.number().finite(false) // accepts Infinity
468
+ * ```
469
+ */
470
+ finite(this: FlagBuilder<C & {
471
+ readonly flagKind: 'number';
472
+ }>, allow?: boolean): FlagBuilder<C>;
400
473
  }
401
474
  /**
402
475
  * Factory that creates {@link FlagBuilder} instances seeded with the correct
@@ -415,11 +488,28 @@ interface FlagFactory {
415
488
  readonly flagKind: 'string';
416
489
  }>;
417
490
  /**
418
- * Number-valued flag.
491
+ * Number-valued flag, with optional numeric constraints.
492
+ *
493
+ * Constraints are enforced at the parse and resolution boundaries. The
494
+ * resolved value type stays `number` — constraints are runtime + schema, not
495
+ * type-level. Bounds are inclusive.
419
496
  *
497
+ * Constraints also compose via chained methods (`.int()`, `.min()`,
498
+ * `.max()`, `.finite()`), which override values set here.
499
+ *
500
+ * @param constraints - Optional numeric constraints. `finite` defaults to
501
+ * `true`, so `Infinity` / `-Infinity` are rejected unless `finite: false`.
502
+ * @defaultValue `undefined` (finite-only, no bounds, non-integer allowed)
420
503
  * @returns A {@link FlagBuilder} for `number` values.
504
+ *
505
+ * @example
506
+ * ```ts
507
+ * flag.number() // finite numbers only
508
+ * flag.number({ int: true, min: 0 }) // non-negative integers
509
+ * flag.number({ finite: false }) // also accepts Infinity
510
+ * ```
421
511
  */
422
- number(): FlagBuilder<{
512
+ number(constraints?: NumberConstraints): FlagBuilder<{
423
513
  readonly valueType: number;
424
514
  readonly presence: 'optional';
425
515
  readonly optionalFallback: 'undefined';
@@ -1 +1 @@
1
- function e(e){return typeof e==`string`?{name:e,hidden:!1}:{name:e.name,hidden:e.hidden}}function t(t){return t.map(e)}function n(e,t){let n=t?.includeHidden??!1,r=t?.kind??`all`;return e.aliases.filter(e=>n||!e.hidden).filter(e=>r===`short`?e.name.length===1:r===`long`?e.name.length>1:!0).map(e=>e.name)}function r(e,n){let r=n?.aliases===void 0?[]:t(n.aliases),{aliases:i,...a}=n??{};return{kind:e,presence:`optional`,defaultValue:void 0,envVar:void 0,configPath:void 0,description:void 0,enumValues:void 0,elementSchema:void 0,prompt:void 0,parseFn:void 0,deprecated:void 0,propagate:!1,...a,aliases:r}}var i=class e{schema;constructor(e){this.schema=e}default(t){return new e({...this.schema,presence:`defaulted`,defaultValue:t})}required(){return new e({...this.schema,presence:`required`})}alias(t,n){return new e({...this.schema,aliases:[...this.schema.aliases,{name:t,hidden:n?.hidden??!1}]})}env(t){return new e({...this.schema,envVar:t})}config(t){return new e({...this.schema,configPath:t})}describe(t){return new e({...this.schema,description:t})}prompt(t){return new e({...this.schema,prompt:t})}deprecated(t){return new e({...this.schema,deprecated:t??!0})}propagate(){return new e({...this.schema,propagate:!0})}};const a={string(){return new i(r(`string`))},number(){return new i(r(`number`))},boolean(){return new i(r(`boolean`,{presence:`defaulted`,defaultValue:!1}))},enum(e){return new i(r(`enum`,{enumValues:e}))},array(e){return new i(r(`array`,{elementSchema:e.schema}))},custom(e){return new i(r(`custom`,{parseFn:e}))}};export{i as FlagBuilder,r as createSchema,a as flag,n as getFlagAliasNames};
1
+ import{assertNumberConstraints as e}from"./number-constraints.mjs";function t(e){return typeof e==`string`?{name:e,hidden:!1}:{name:e.name,hidden:e.hidden}}function n(e){return e.map(t)}function r(e,t){let n=t?.includeHidden??!1,r=t?.kind??`all`;return e.aliases.filter(e=>n||!e.hidden).filter(e=>r===`short`?e.name.length===1:r===`long`?e.name.length>1:!0).map(e=>e.name)}function i(e,t){let r=t?.aliases===void 0?[]:n(t.aliases),{aliases:i,...a}=t??{};return{kind:e,presence:`optional`,defaultValue:void 0,envVar:void 0,configPath:void 0,description:void 0,enumValues:void 0,numberConstraints:void 0,elementSchema:void 0,prompt:void 0,parseFn:void 0,deprecated:void 0,propagate:!1,...a,aliases:r}}var a=class t{schema;constructor(e){this.schema=e}default(e){return new t({...this.schema,presence:`defaulted`,defaultValue:e})}required(){return new t({...this.schema,presence:`required`})}alias(e,n){return new t({...this.schema,aliases:[...this.schema.aliases,{name:e,hidden:n?.hidden??!1}]})}env(e){return new t({...this.schema,envVar:e})}config(e){return new t({...this.schema,configPath:e})}describe(e){return new t({...this.schema,description:e})}prompt(e){return new t({...this.schema,prompt:e})}deprecated(e){return new t({...this.schema,deprecated:e??!0})}propagate(){return new t({...this.schema,propagate:!0})}int(e=!0){return new t({...this.schema,numberConstraints:{...this.schema.numberConstraints,int:e}})}min(n){let r={...this.schema.numberConstraints,min:n};return e(r),new t({...this.schema,numberConstraints:r})}max(n){let r={...this.schema.numberConstraints,max:n};return e(r),new t({...this.schema,numberConstraints:r})}finite(e=!0){return new t({...this.schema,numberConstraints:{...this.schema.numberConstraints,finite:e}})}};const o={string(){return new a(i(`string`))},number(t){return t!==void 0&&e(t),new a(i(`number`,t===void 0?{}:{numberConstraints:t}))},boolean(){return new a(i(`boolean`,{presence:`defaulted`,defaultValue:!1}))},enum(e){return new a(i(`enum`,{enumValues:e}))},array(e){return new a(i(`array`,{elementSchema:e.schema}))},custom(e){return new a(i(`custom`,{parseFn:e}))}};export{a as FlagBuilder,i as createSchema,o as flag,r as getFlagAliasNames};
@@ -1,8 +1,9 @@
1
1
  import { ActivityEvent, Fallback, ProgressHandle, ProgressOptions, SpinnerHandle, SpinnerOptions, TableColumn, TableFormat, TableOptions, TableStream } from "./activity.mjs";
2
+ import { NumberConstraintViolation, NumberConstraints, describeNumberConstraintViolation, validateNumberConstraints } from "./number-constraints.mjs";
2
3
  import { ARG_KINDS, ARG_PRESENCES, ArgBuilder, ArgConfig, ArgFactory, ArgKind, ArgParseFn, ArgPresence, ArgSchema, InferArg, InferArgs, ResolvedArgValue, WithArgPresence, WithVariadic, arg, createArgSchema } from "./arg.mjs";
3
4
  import { ConfirmPromptConfig, InputPromptConfig, MultiselectPromptConfig, PROMPT_KINDS, PromptConfig, PromptConfigBase, PromptKind, PromptResult, SelectChoice, SelectPromptConfig } from "./prompt.mjs";
4
5
  import { FLAG_KINDS, FLAG_PRESENCES, FlagAlias, FlagBuilder, FlagConfig, FlagFactory, FlagKind, FlagParseFn, FlagPresence, FlagSchema, FlagSchemaOverrides, InferFlag, InferFlags, ResolvedValue, WithPresence, createSchema, flag } from "./flag.mjs";
5
6
  import { ErasedMiddlewareHandler, Middleware, MiddlewareHandler, MiddlewareParams, middleware } from "./middleware.mjs";
6
7
  import { RunOptions, RunResult } from "./run.mjs";
7
8
  import { ActionHandler, ActionParams, AnyCommandBuilder, CommandArgEntry, CommandBuilder, CommandConfig, CommandExample, CommandMeta, CommandSchema, DeriveHandler, DeriveParams, ErasedCommand, ErasedDeriveHandler, ErasedInteractiveResolver, InteractiveParams, InteractiveResolver, InteractiveResult, Out, command, group } from "./command.mjs";
8
- export { ARG_KINDS, ARG_PRESENCES, type ActionHandler, type ActionParams, type ActivityEvent, type AnyCommandBuilder, ArgBuilder, type ArgConfig, type ArgFactory, type ArgKind, type ArgParseFn, type ArgPresence, type ArgSchema, type CommandArgEntry, CommandBuilder, type CommandConfig, type CommandExample, type CommandMeta, type CommandSchema, type ConfirmPromptConfig, type DeriveHandler, type DeriveParams, type ErasedCommand, type ErasedDeriveHandler, type ErasedInteractiveResolver, type ErasedMiddlewareHandler, FLAG_KINDS, FLAG_PRESENCES, type Fallback, type FlagAlias, FlagBuilder, type FlagConfig, type FlagFactory, type FlagKind, type FlagParseFn, type FlagPresence, type FlagSchema, type FlagSchemaOverrides, type InferArg, type InferArgs, type InferFlag, type InferFlags, type InputPromptConfig, type InteractiveParams, type InteractiveResolver, type InteractiveResult, type Middleware, type MiddlewareHandler, type MiddlewareParams, type MultiselectPromptConfig, type Out, PROMPT_KINDS, type ProgressHandle, type ProgressOptions, type PromptConfig, type PromptConfigBase, type PromptKind, type PromptResult, type ResolvedArgValue, type ResolvedValue, type RunOptions, type RunResult, type SelectChoice, type SelectPromptConfig, type SpinnerHandle, type SpinnerOptions, type TableColumn, type TableFormat, type TableOptions, type TableStream, type WithArgPresence, type WithPresence, type WithVariadic, arg, command, createArgSchema, createSchema, flag, group, middleware };
9
+ export { ARG_KINDS, ARG_PRESENCES, type ActionHandler, type ActionParams, type ActivityEvent, type AnyCommandBuilder, ArgBuilder, type ArgConfig, type ArgFactory, type ArgKind, type ArgParseFn, type ArgPresence, type ArgSchema, type CommandArgEntry, CommandBuilder, type CommandConfig, type CommandExample, type CommandMeta, type CommandSchema, type ConfirmPromptConfig, type DeriveHandler, type DeriveParams, type ErasedCommand, type ErasedDeriveHandler, type ErasedInteractiveResolver, type ErasedMiddlewareHandler, FLAG_KINDS, FLAG_PRESENCES, type Fallback, type FlagAlias, FlagBuilder, type FlagConfig, type FlagFactory, type FlagKind, type FlagParseFn, type FlagPresence, type FlagSchema, type FlagSchemaOverrides, type InferArg, type InferArgs, type InferFlag, type InferFlags, type InputPromptConfig, type InteractiveParams, type InteractiveResolver, type InteractiveResult, type Middleware, type MiddlewareHandler, type MiddlewareParams, type MultiselectPromptConfig, type NumberConstraintViolation, type NumberConstraints, type Out, PROMPT_KINDS, type ProgressHandle, type ProgressOptions, type PromptConfig, type PromptConfigBase, type PromptKind, type PromptResult, type ResolvedArgValue, type ResolvedValue, type RunOptions, type RunResult, type SelectChoice, type SelectPromptConfig, type SpinnerHandle, type SpinnerOptions, type TableColumn, type TableFormat, type TableOptions, type TableStream, type WithArgPresence, type WithPresence, type WithVariadic, arg, command, createArgSchema, createSchema, describeNumberConstraintViolation, flag, group, middleware, validateNumberConstraints };
@@ -0,0 +1,96 @@
1
+ //#region src/core/schema/number-constraints.d.ts
2
+ /**
3
+ * Numeric constraints for number-valued flags and args.
4
+ *
5
+ * A single, shared representation and validator so the parse path
6
+ * (`core/parse`) and the resolver coercion path (`core/resolve/coerce`) cannot
7
+ * drift: both import {@link validateNumberConstraints} and apply the checks in
8
+ * the same order (finite → int → min → max).
9
+ *
10
+ * @module dreamcli/core/schema/number-constraints
11
+ */
12
+ /**
13
+ * Runtime numeric constraints attached to a number flag/arg schema.
14
+ *
15
+ * Bounds are **inclusive**. All fields are optional; an absent field means "no
16
+ * constraint" except for {@link NumberConstraints.finite | finite}, which
17
+ * defaults to `true` (so `Infinity` / `-Infinity` are rejected unless opted
18
+ * back in).
19
+ */
20
+ interface NumberConstraints {
21
+ /**
22
+ * Inclusive lower bound. Values below this are rejected.
23
+ * @defaultValue `undefined` (no lower bound)
24
+ */
25
+ readonly min?: number;
26
+ /**
27
+ * Inclusive upper bound. Values above this are rejected.
28
+ * @defaultValue `undefined` (no upper bound)
29
+ */
30
+ readonly max?: number;
31
+ /**
32
+ * Require an integer value. Non-integers (e.g. `3.7`) are rejected.
33
+ * @defaultValue `false`
34
+ */
35
+ readonly int?: boolean;
36
+ /**
37
+ * Require a finite value. When `true`, `Infinity` / `-Infinity` are rejected.
38
+ * @defaultValue `true`
39
+ */
40
+ readonly finite?: boolean;
41
+ }
42
+ /**
43
+ * A failed numeric constraint, discriminated by which rule was violated.
44
+ *
45
+ * `min` / `max` carry the offending bound so callers can render it.
46
+ */
47
+ type NumberConstraintViolation = {
48
+ readonly kind: 'finite';
49
+ } | {
50
+ readonly kind: 'int';
51
+ } | {
52
+ readonly kind: 'min';
53
+ readonly bound: number;
54
+ } | {
55
+ readonly kind: 'max';
56
+ readonly bound: number;
57
+ };
58
+ /** Default for {@link NumberConstraints.finite} — reject `Infinity` unless opted out. */
59
+ declare const DEFAULT_FINITE = true;
60
+ /**
61
+ * Validate a numeric value against constraints.
62
+ *
63
+ * The single source of truth for numeric-constraint checks, shared by the
64
+ * parse and coerce paths. Checks run in a fixed order — **finite → int → min →
65
+ * max** — and the first failure is returned. `NaN` is always rejected as a
66
+ * `finite` violation, regardless of the `finite` option (a non-finite value can
67
+ * otherwise slip past `min`/`max`, since `NaN < x` and `NaN > x` are both false).
68
+ *
69
+ * @param value - The numeric value to validate.
70
+ * @param constraints - Constraints to enforce, or `undefined` for defaults.
71
+ * @returns The first {@link NumberConstraintViolation}, or `undefined` if valid.
72
+ */
73
+ declare function validateNumberConstraints(value: number, constraints: NumberConstraints | undefined): NumberConstraintViolation | undefined;
74
+ /**
75
+ * Render a terse, human-readable reason for a constraint violation.
76
+ *
77
+ * @param violation - The violation to describe.
78
+ * @returns A message suffix such as `must be an integer` or `must be >= 0`.
79
+ */
80
+ declare function describeNumberConstraintViolation(violation: NumberConstraintViolation): string;
81
+ /**
82
+ * Assert that a constraints object is well-formed at schema-construction time.
83
+ *
84
+ * `min` / `max` must be finite — an infinite or `NaN` bound is meaningless (omit
85
+ * the field for "no bound") and would serialize to `null` in the emitted JSON
86
+ * Schema. An inverted range (`min > max`) is also rejected, since it makes the
87
+ * flag/arg permanently unsatisfiable. Throws so the misconfiguration surfaces
88
+ * where the flag/arg is declared, not at parse time.
89
+ *
90
+ * @param constraints - The constraints to validate.
91
+ * @throws RangeError if `min` or `max` is non-finite (`Infinity` / `-Infinity` /
92
+ * `NaN`), or if `min` exceeds `max`.
93
+ */
94
+ declare function assertNumberConstraints(constraints: NumberConstraints): void;
95
+ //#endregion
96
+ export { DEFAULT_FINITE, type NumberConstraintViolation, type NumberConstraints, assertNumberConstraints, describeNumberConstraintViolation, validateNumberConstraints };
@@ -0,0 +1 @@
1
+ function e(e,t){if(Number.isNaN(e)||(t?.finite??!0)&&!Number.isFinite(e))return{kind:`finite`};if(t?.int===!0&&!Number.isInteger(e))return{kind:`int`};if(t?.min!==void 0&&e<t.min)return{kind:`min`,bound:t.min};if(t?.max!==void 0&&e>t.max)return{kind:`max`,bound:t.max}}function t(e){switch(e.kind){case`finite`:return`must be a finite number`;case`int`:return`must be an integer`;case`min`:return`must be >= ${e.bound}`;case`max`:return`must be <= ${e.bound}`}}function n(e){if(e.min!==void 0&&!Number.isFinite(e.min))throw RangeError(`number constraint 'min' must be a finite number (got ${e.min}); omit it for no lower bound`);if(e.max!==void 0&&!Number.isFinite(e.max))throw RangeError(`number constraint 'max' must be a finite number (got ${e.max}); omit it for no upper bound`);if(e.min!==void 0&&e.max!==void 0&&e.min>e.max)throw RangeError(`number constraint 'min' (${e.min}) must not exceed 'max' (${e.max})`)}export{n as assertNumberConstraints,t as describeNumberConstraintViolation,e as validateNumberConstraints};
@@ -29,6 +29,12 @@ interface PromptConfigBase {
29
29
  interface ConfirmPromptConfig extends PromptConfigBase {
30
30
  /** Discriminator identifying this as a yes/no confirmation prompt. */
31
31
  readonly kind: 'confirm';
32
+ /**
33
+ * Value used when the user submits an empty line (presses Enter). Also
34
+ * drives the displayed hint: `true` → `(Y/n)`, `false` → `(y/N)`.
35
+ * @defaultValue `true`
36
+ */
37
+ readonly default?: boolean;
32
38
  }
33
39
  /** Free-text input prompt — maps to `string` and `number` flags. Part of {@link PromptConfig}. */
34
40
  interface InputPromptConfig extends PromptConfigBase {
@@ -36,6 +42,15 @@ interface InputPromptConfig extends PromptConfigBase {
36
42
  readonly kind: 'input';
37
43
  /** Placeholder text shown before user types (informational only). */
38
44
  readonly placeholder?: string;
45
+ /**
46
+ * Value used when the user submits an empty line (presses Enter), shown in
47
+ * the hint as `(default: <value>)`. When set, an empty submission resolves
48
+ * to this value without running {@link InputPromptConfig.validate | validate}.
49
+ * When omitted, an empty submission is treated as "no answer" so resolution
50
+ * falls through to the flag's `.default()`.
51
+ * @defaultValue `undefined`
52
+ */
53
+ readonly default?: string;
39
54
  /**
40
55
  * Inline validation function. Return `true` if valid, or a string
41
56
  * error message if invalid. Called before coercion to flag kind.
@@ -133,10 +133,10 @@ interface RunOptions {
133
133
  /**
134
134
  * Structured result from {@linkcode runCommand}.
135
135
  *
136
- * Contains the exit code, captured stdout/stderr output, recorded
137
- * {@linkcode ActivityEvent | activity events}, and an `error` field.
138
- * `error` is `undefined` when execution completed without throwing, even if
139
- * the handler requested a non-zero status via {@linkcode Out.setExitCode}.
136
+ * Contains the exit code, captured stdout/stderr output, recorded
137
+ * {@linkcode ActivityEvent | activity events}, and an `error` field.
138
+ * `error` is `undefined` when execution completed without throwing, even if
139
+ * the handler requested a non-zero status via {@linkcode Out.setExitCode}.
140
140
  *
141
141
  * @example
142
142
  * ```ts
@@ -6,16 +6,20 @@ import { RunnableCommand } from "../schema/command.mjs";
6
6
  * Run a command builder against the given argv with injected options.
7
7
  *
8
8
  * This is the testkit wrapper around the shared executor:
9
- * 1. Create or reuse capture output
10
- * 2. Build standalone schema/meta defaults when CLI dispatch did not
11
- * 3. Delegate parse -> resolve -> execute to the shared executor
12
- * 4. Return the structured result with captured buffers
9
+ * 1. Apply the CLI root-flag layer (detect/strip `--json`) so copied real argv works
10
+ * 2. Create or reuse capture output
11
+ * 3. Build standalone schema/meta defaults when CLI dispatch did not
12
+ * 4. Delegate parse -> resolve -> execute to the shared executor
13
+ * 5. Return the structured result with captured buffers
13
14
  *
14
15
  * Errors are normalized by the shared executor into structured {@linkcode RunResult}s
15
16
  * with appropriate exit codes. The function never throws.
16
17
  *
17
18
  * @param cmd - The command builder (must have an action handler)
18
- * @param argv - Raw argv strings (NOT including the command name itself)
19
+ * @param argv - Raw argv strings (NOT including the command name itself). A
20
+ * CLI-level `--json` before the `--` separator is honored and stripped here,
21
+ * just like the real CLI root — so `['--json']` enables JSON mode rather than
22
+ * failing as an unknown flag. Equivalent to passing `{ jsonMode: true }`.
19
23
  * @param options - Injectable runtime state
20
24
  * @returns Structured run result with exit code and captured output
21
25
  */
@@ -1 +1 @@
1
- import{createCaptureOutput as e}from"../output/index.mjs";import{buildRunResult as t,executeCommand as n}from"../execution/index.mjs";async function r(r,i,a){let o,s;if(a?.out!==void 0)o=a.out,s=a.captured??{stdout:[],stderr:[],activity:[]};else{let t={...a?.verbosity===void 0?{}:{verbosity:a.verbosity},...a?.jsonMode===void 0?{}:{jsonMode:a.jsonMode},...a?.isTTY===void 0?{}:{isTTY:a.isTTY}};[o,s]=e(Object.keys(t).length>0?t:void 0)}let c=a?.mergedSchema??r.schema,l=a?.meta??{name:c.name,bin:a?.help?.binName??c.name,version:void 0,command:c.name};return t(await n({command:r,argv:i,out:o,schema:c,meta:l,...a===void 0?{}:{options:a}}),s)}export{r as runCommand};
1
+ import{createCaptureOutput as e}from"../output/index.mjs";import{includesBeforeSeparator as t,stripBeforeSeparator as n}from"../parse/index.mjs";import{buildRunResult as r,executeCommand as i}from"../execution/index.mjs";async function a(a,o,s){let c=t(o,`--json`),l=c||s?.jsonMode===!0,u=c?n(o,`--json`):o,d,f;if(s?.out!==void 0)d=s.out,f=s.captured??{stdout:[],stderr:[],activity:[]};else{let t={...s?.verbosity===void 0?{}:{verbosity:s.verbosity},...l?{jsonMode:l}:{},...s?.isTTY===void 0?{}:{isTTY:s.isTTY}};[d,f]=e(Object.keys(t).length>0?t:void 0)}let p=s?.mergedSchema??a.schema,m=s?.meta??{name:p.name,bin:s?.help?.binName??p.name,version:void 0,command:p.name},h=s===void 0?l?{jsonMode:l}:void 0:{...s,...l?{jsonMode:l}:{}};return r(await i({command:a,argv:u,out:d,schema:p,meta:m,...h===void 0?{}:{options:h}}),f)}export{a as runCommand};
package/dist/index.d.mts CHANGED
@@ -1,4 +1,5 @@
1
1
  import { ActivityEvent, Fallback, ProgressHandle, ProgressOptions, SpinnerHandle, SpinnerOptions, TableColumn, TableFormat, TableOptions, TableStream } from "./core/schema/activity.mjs";
2
+ import { NumberConstraintViolation, NumberConstraints } from "./core/schema/number-constraints.mjs";
2
3
  import { ArgBuilder, ArgConfig, ArgFactory, ArgKind, ArgParseFn, ArgPresence, ArgSchema, InferArg, InferArgs, ResolvedArgValue, WithArgPresence, WithVariadic, arg, createArgSchema } from "./core/schema/arg.mjs";
3
4
  import { ConfirmPromptConfig, InputPromptConfig, MultiselectPromptConfig, PromptConfig, PromptConfigBase, PromptKind, PromptResult, SelectChoice, SelectPromptConfig } from "./core/schema/prompt.mjs";
4
5
  import { FlagBuilder, FlagConfig, FlagFactory, FlagKind, FlagParseFn, FlagPresence, FlagSchema, InferFlag, InferFlags, ResolvedValue, WithPresence, createSchema, flag } from "./core/schema/flag.mjs";
@@ -27,4 +28,4 @@ import { SHELLS, Shell, generateCompletion } from "./core/completion/index.mjs";
27
28
  import { ConfigAdapter, ConfigDiscoveryOptions, ConfigDiscoveryResult, ConfigFound, ConfigNotFound, FormatLoader, buildConfigSearchPaths, configFormat, discoverConfig } from "./core/config/index.mjs";
28
29
  import { CLIBuilder, CLIOptions, CLIRunOptions, CLISchema, ConfigSettings, InferNameOption, ManifestPresetSettings, ManifestSettings, PackageJsonSettings, ResolvedManifestSettings, cli } from "./core/cli/index.mjs";
29
30
  import { JsonSchemaOptions, definitionMetaSchema, generateInputSchema, generateSchema } from "./core/json-schema/index.mjs";
30
- export { type ActionHandler, type ActionParams, type ActivityEvent, type AnyCommandBuilder, ArgBuilder, type ArgConfig, type ArgFactory, type ArgKind, type ArgParseFn, type ArgPresence, type ArgSchema, type BeforeParseParams, CLIBuilder, CLIError, type CLIErrorJSON, type CLIErrorOptions, type CLIOptions, type CLIPlugin, type CLIPluginHooks, type CLIRunOptions, type CLISchema, type CommandArgEntry, CommandBuilder, type CommandConfig, type CommandExample, type CommandMeta, type CommandSchema, type CompletionOptions, type ConfigAdapter, type ConfigDiscoveryOptions, type ConfigDiscoveryResult, type ConfigFound, type ConfigNotFound, type ConfigSettings, type ConfirmPromptConfig, type DeprecationWarning, type DeriveHandler, type DeriveParams, type ErrorCode, type Fallback, FlagBuilder, type FlagConfig, type FlagFactory, type FlagKind, type FlagParseFn, type FlagPresence, type FlagSchema, type FormatLoader, type HelpLinks, type HelpOptions, type InferArg, type InferArgs, type InferFlag, type InferFlags, type InferNameOption, type InputPromptConfig, type InteractiveParams, type InteractiveResolver, type InteractiveResult, type JsonSchemaOptions, type ManifestDiscoveryOptions, type ManifestPresetSettings, type ManifestSettings, type Middleware, type MiddlewareHandler, type MiddlewareParams, type MultiselectPromptConfig, type Out, type OutputOptions, type PackageJsonAdapter, type PackageJsonData, type PackageJsonSettings, type PackageRepository, ParseError, type ParseErrorCode, type ParseErrorOptions, type ParseResult, type PluginCommandContext, type ProgressHandle, type ProgressOptions, type PromptConfig, type PromptConfigBase, type PromptEngine, type PromptKind, type PromptResult, type ReadFn, type ResolveOptions, type ResolveResult, type ResolvedArgValue, type ResolvedCommandParams, type ResolvedManifestSettings, type ResolvedMultiselectPromptConfig, type ResolvedPromptConfig, type ResolvedSelectPromptConfig, type ResolvedValue, type RunResult, SHELLS, type SelectChoice, type SelectPromptConfig, type Shell, type SpinnerHandle, type SpinnerOptions, type TableColumn, type TableFormat, type TableOptions, type TableStream, type Token, ValidationError, type ValidationErrorCode, type ValidationErrorOptions, type Verbosity, type WithArgPresence, type WithPresence, type WithVariadic, type WriteFn, arg, buildConfigSearchPaths, cli, command, configFormat, createArgSchema, createOutput, createSchema, createTerminalPrompter, definitionMetaSchema, discoverConfig, discoverManifest, discoverPackageJson, flag, formatHelp, generateBashCompletion, generateCompletion, generateFishCompletion, generateInputSchema, generatePowerShellCompletion, generateSchema, generateZshCompletion, group, inferCliName, isCLIError, isParseError, isValidationError, middleware, osc8, packageRepositoryUrl, parse, plugin, resolve, resolvePromptConfig, tokenize, visibleWidth };
31
+ export { type ActionHandler, type ActionParams, type ActivityEvent, type AnyCommandBuilder, ArgBuilder, type ArgConfig, type ArgFactory, type ArgKind, type ArgParseFn, type ArgPresence, type ArgSchema, type BeforeParseParams, CLIBuilder, CLIError, type CLIErrorJSON, type CLIErrorOptions, type CLIOptions, type CLIPlugin, type CLIPluginHooks, type CLIRunOptions, type CLISchema, type CommandArgEntry, CommandBuilder, type CommandConfig, type CommandExample, type CommandMeta, type CommandSchema, type CompletionOptions, type ConfigAdapter, type ConfigDiscoveryOptions, type ConfigDiscoveryResult, type ConfigFound, type ConfigNotFound, type ConfigSettings, type ConfirmPromptConfig, type DeprecationWarning, type DeriveHandler, type DeriveParams, type ErrorCode, type Fallback, FlagBuilder, type FlagConfig, type FlagFactory, type FlagKind, type FlagParseFn, type FlagPresence, type FlagSchema, type FormatLoader, type HelpLinks, type HelpOptions, type InferArg, type InferArgs, type InferFlag, type InferFlags, type InferNameOption, type InputPromptConfig, type InteractiveParams, type InteractiveResolver, type InteractiveResult, type JsonSchemaOptions, type ManifestDiscoveryOptions, type ManifestPresetSettings, type ManifestSettings, type Middleware, type MiddlewareHandler, type MiddlewareParams, type MultiselectPromptConfig, type NumberConstraintViolation, type NumberConstraints, type Out, type OutputOptions, type PackageJsonAdapter, type PackageJsonData, type PackageJsonSettings, type PackageRepository, ParseError, type ParseErrorCode, type ParseErrorOptions, type ParseResult, type PluginCommandContext, type ProgressHandle, type ProgressOptions, type PromptConfig, type PromptConfigBase, type PromptEngine, type PromptKind, type PromptResult, type ReadFn, type ResolveOptions, type ResolveResult, type ResolvedArgValue, type ResolvedCommandParams, type ResolvedManifestSettings, type ResolvedMultiselectPromptConfig, type ResolvedPromptConfig, type ResolvedSelectPromptConfig, type ResolvedValue, type RunResult, SHELLS, type SelectChoice, type SelectPromptConfig, type Shell, type SpinnerHandle, type SpinnerOptions, type TableColumn, type TableFormat, type TableOptions, type TableStream, type Token, ValidationError, type ValidationErrorCode, type ValidationErrorOptions, type Verbosity, type WithArgPresence, type WithPresence, type WithVariadic, type WriteFn, arg, buildConfigSearchPaths, cli, command, configFormat, createArgSchema, createOutput, createSchema, createTerminalPrompter, definitionMetaSchema, discoverConfig, discoverManifest, discoverPackageJson, flag, formatHelp, generateBashCompletion, generateCompletion, generateFishCompletion, generateInputSchema, generatePowerShellCompletion, generateSchema, generateZshCompletion, group, inferCliName, isCLIError, isParseError, isValidationError, middleware, osc8, packageRepositoryUrl, parse, plugin, resolve, resolvePromptConfig, tokenize, visibleWidth };
package/dist/index.mjs CHANGED
@@ -1 +1 @@
1
- import{FlagBuilder as e,createSchema as t,flag as n}from"./core/schema/flag.mjs";import{generateBashCompletion as r}from"./core/completion/shells/bash.mjs";import{generateFishCompletion as i}from"./core/completion/shells/fish.mjs";import{generatePowerShellCompletion as a}from"./core/completion/shells/powershell.mjs";import{CLIError as o,ParseError as s,ValidationError as c,isCLIError as l,isParseError as u,isValidationError as d}from"./core/errors/index.mjs";import{generateZshCompletion as f}from"./core/completion/shells/zsh.mjs";import{SHELLS as p,generateCompletion as m}from"./core/completion/index.mjs";import{osc8 as h,visibleWidth as g}from"./core/help/ansi.mjs";import{formatHelp as _}from"./core/help/index.mjs";import{createOutput as v}from"./core/output/index.mjs";import{parse as y,tokenize as b}from"./core/parse/index.mjs";import{createTerminalPrompter as x,resolvePromptConfig as S}from"./core/prompt/index.mjs";import{resolve as C}from"./core/resolve/index.mjs";import{ArgBuilder as w,arg as T,createArgSchema as E}from"./core/schema/arg.mjs";import{CommandBuilder as D,command as O,group as k}from"./core/schema/command.mjs";import{discoverManifest as A,discoverPackageJson as j,inferCliName as M,packageRepositoryUrl as N}from"./core/config/package-json.mjs";import{plugin as P}from"./core/cli/plugin.mjs";import{buildConfigSearchPaths as F,configFormat as I,discoverConfig as L}from"./core/config/index.mjs";import{CLIBuilder as R,cli as z}from"./core/cli/index.mjs";import{definitionMetaSchema as B,generateInputSchema as V,generateSchema as H}from"./core/json-schema/index.mjs";import{middleware as U}from"./core/schema/middleware.mjs";export{w as ArgBuilder,R as CLIBuilder,o as CLIError,D as CommandBuilder,e as FlagBuilder,s as ParseError,p as SHELLS,c as ValidationError,T as arg,F as buildConfigSearchPaths,z as cli,O as command,I as configFormat,E as createArgSchema,v as createOutput,t as createSchema,x as createTerminalPrompter,B as definitionMetaSchema,L as discoverConfig,A as discoverManifest,j as discoverPackageJson,n as flag,_ as formatHelp,r as generateBashCompletion,m as generateCompletion,i as generateFishCompletion,V as generateInputSchema,a as generatePowerShellCompletion,H as generateSchema,f as generateZshCompletion,k as group,M as inferCliName,l as isCLIError,u as isParseError,d as isValidationError,U as middleware,h as osc8,N as packageRepositoryUrl,y as parse,P as plugin,C as resolve,S as resolvePromptConfig,b as tokenize,g as visibleWidth};
1
+ import{FlagBuilder as e,createSchema as t,flag as n}from"./core/schema/flag.mjs";import{generateBashCompletion as r}from"./core/completion/shells/bash.mjs";import{generateFishCompletion as i}from"./core/completion/shells/fish.mjs";import{generatePowerShellCompletion as a}from"./core/completion/shells/powershell.mjs";import{CLIError as o,ParseError as s,ValidationError as c,isCLIError as l,isParseError as u,isValidationError as d}from"./core/errors/index.mjs";import{generateZshCompletion as f}from"./core/completion/shells/zsh.mjs";import{SHELLS as p,generateCompletion as m}from"./core/completion/index.mjs";import{osc8 as h,visibleWidth as g}from"./core/help/ansi.mjs";import{formatHelp as _}from"./core/help/index.mjs";import{createOutput as v}from"./core/output/index.mjs";import{ArgBuilder as y,arg as b,createArgSchema as x}from"./core/schema/arg.mjs";import{CommandBuilder as S,command as C,group as w}from"./core/schema/command.mjs";import{middleware as T}from"./core/schema/middleware.mjs";import{parse as E,tokenize as D}from"./core/parse/index.mjs";import{createTerminalPrompter as O,resolvePromptConfig as k}from"./core/prompt/index.mjs";import{resolve as A}from"./core/resolve/index.mjs";import{discoverManifest as j,discoverPackageJson as M,inferCliName as N,packageRepositoryUrl as P}from"./core/config/package-json.mjs";import{plugin as F}from"./core/cli/plugin.mjs";import{buildConfigSearchPaths as I,configFormat as L,discoverConfig as R}from"./core/config/index.mjs";import{CLIBuilder as z,cli as B}from"./core/cli/index.mjs";import{definitionMetaSchema as V,generateInputSchema as H,generateSchema as U}from"./core/json-schema/index.mjs";export{y as ArgBuilder,z as CLIBuilder,o as CLIError,S as CommandBuilder,e as FlagBuilder,s as ParseError,p as SHELLS,c as ValidationError,b as arg,I as buildConfigSearchPaths,B as cli,C as command,L as configFormat,x as createArgSchema,v as createOutput,t as createSchema,O as createTerminalPrompter,V as definitionMetaSchema,R as discoverConfig,j as discoverManifest,M as discoverPackageJson,n as flag,_ as formatHelp,r as generateBashCompletion,m as generateCompletion,i as generateFishCompletion,H as generateInputSchema,a as generatePowerShellCompletion,U as generateSchema,f as generateZshCompletion,w as group,N as inferCliName,l as isCLIError,u as isParseError,d as isValidationError,T as middleware,h as osc8,P as packageRepositoryUrl,E as parse,F as plugin,A as resolve,k as resolvePromptConfig,D as tokenize,g as visibleWidth};
@@ -1 +1 @@
1
- import{assertRuntimeVersionSupported as e}from"./support.mjs";import{createNodeAdapter as t}from"./node.mjs";import{createBunAdapter as n}from"./bun.mjs";import{createDenoAdapter as r}from"./deno.mjs";import{detectRuntime as i}from"./detect.mjs";function a(e,t){switch(e){case`bun`:return t.Bun?.version;case`deno`:return t.Deno?.version?.deno;case`node`:return t.process?.versions?.node;case`unknown`:return;default:return e}}function o(e){if(typeof e!=`object`||!e)return!1;let t=e;return Array.isArray(t.args)&&typeof t.cwd==`function`&&typeof t.exit==`function`&&typeof t.readTextFile==`function`&&typeof t.env?.get==`function`&&typeof t.env.toObject==`function`&&typeof t.stdout?.writeSync==`function`&&typeof t.stdout.isTerminal==`function`&&typeof t.stderr?.writeSync==`function`&&typeof t.stdin?.isTerminal==`function`&&typeof t.stdin?.readable?.getReader==`function`}function s(e){let t=e.Deno;return o(t)?t:void 0}function c(o){let c=o??globalThis,l=i(c);switch(l!==`unknown`&&e(l,a(l,c)),l){case`bun`:return n();case`deno`:return r(s(c));case`node`:case`unknown`:return t();default:return l}}export{c as createAdapter};
1
+ import{createNodeAdapter as e}from"./node.mjs";import{createBunAdapter as t}from"./bun.mjs";import{createDenoAdapter as n}from"./deno.mjs";import{detectRuntime as r}from"./detect.mjs";function i(e){if(typeof e!=`object`||!e)return!1;let t=e;return Array.isArray(t.args)&&typeof t.cwd==`function`&&typeof t.exit==`function`&&typeof t.readTextFile==`function`&&typeof t.env?.get==`function`&&typeof t.env.toObject==`function`&&typeof t.stdout?.writeSync==`function`&&typeof t.stdout.isTerminal==`function`&&typeof t.stderr?.writeSync==`function`&&typeof t.stdin?.isTerminal==`function`&&typeof t.stdin?.readable?.getReader==`function`}function a(e){let t=e.Deno;return i(t)?t:void 0}function o(i){let o=i??globalThis,s=r(o);switch(s){case`bun`:return t();case`deno`:return n(a(o));case`node`:case`unknown`:return e();default:return s}}export{o as createAdapter};
@@ -1 +1 @@
1
- import{assertRuntimeVersionSupported as e}from"./support.mjs";import{createNodeAdapter as t}from"./node.mjs";function n(e){return e?.versions?.bun===void 0?globalThis.Bun?.version:e.versions.bun}function r(r){return e(`bun`,n(r)),t(r)}export{r as createBunAdapter};
1
+ import{createNodeAdapter as e}from"./node.mjs";function t(t){return e(t)}export{t as createBunAdapter};
@@ -1,2 +1,2 @@
1
- import{resolveConfigDirectory as e,resolveHomeDirectory as t}from"./paths.mjs";import{assertRuntimeVersionSupported as n}from"./support.mjs";function r(e,t){if(typeof e!=`object`||!e||!(`name`in e))return!1;let n=e;return typeof n.name==`string`&&n.name===t}function i(e){try{return e.env.toObject()}catch(e){if(r(e,`PermissionDenied`))return{};throw e}}function a(e){try{return e.cwd()}catch(e){if(r(e,`PermissionDenied`))return`/`;throw e}}function o(e){let t=e??s();n(`deno`,t.version?.deno);let o=new TextEncoder,f=[`deno`,`run`,...t.args],p=i(t),m=a(t),h=e=>{t.stdout.writeSync(o.encode(e))},g=e=>{t.stderr.writeSync(o.encode(e))},_=l(t),v=async e=>{try{return await t.readTextFile(e)}catch(e){if(r(e,`NotFound`)||r(e,`PermissionDenied`))return null;throw e}},y=u(p,t.build.os===`windows`),b=d(p,y,t.build.os===`windows`),x=t.stdin.isTerminal();return{argv:f,env:p,cwd:m,stdout:h,stderr:g,stdin:_,readStdin:()=>c(t,x),isTTY:t.stdout.isTerminal(),stdinIsTTY:x,exit:e=>t.exit(e),readFile:v,homedir:y,configDir:b}}function s(){return globalThis.Deno}async function c(e,t){if(t)return null;let n=e.stdin.readable.getReader(),r=new TextDecoder,i=[];try{for(;;){let{value:e,done:t}=await n.read();if(t){i.push(r.decode());break}i.push(r.decode(e,{stream:!0}))}}finally{n.releaseLock()}return i.join(``)}function l(e){let t=new TextDecoder,n=``,r=!1;return async()=>{let i=e.stdin.readable.getReader();try{for(;;){let e=n.indexOf(`
2
- `);if(e!==-1){let t=n.slice(0,e).replace(/\r$/,``);return n=n.slice(e+1),t}if(r){if(n.length===0)return null;let e=n;return n=``,e}let{value:a,done:o}=await i.read();if(o){n+=t.decode(),r=!0;continue}n+=t.decode(a,{stream:!0})}}finally{i.releaseLock()}}}function u(e,n){return t(e,n)}function d(t,n,r){return e(t,r,n)}export{o as createDenoAdapter};
1
+ import{resolveConfigDirectory as e,resolveHomeDirectory as t}from"./paths.mjs";function n(e,t){if(typeof e!=`object`||!e||!(`name`in e))return!1;let n=e;return typeof n.name==`string`&&n.name===t}function r(e){try{return e.env.toObject()}catch(e){if(n(e,`PermissionDenied`))return{};throw e}}function i(e){try{return e.cwd()}catch(e){if(n(e,`PermissionDenied`))return`/`;throw e}}function a(e){let t=e??o(),a=new TextEncoder,d=[`deno`,`run`,...t.args],f=r(t),p=i(t),m=e=>{t.stdout.writeSync(a.encode(e))},h=e=>{t.stderr.writeSync(a.encode(e))},g=c(t),_=async e=>{try{return await t.readTextFile(e)}catch(e){if(n(e,`NotFound`)||n(e,`PermissionDenied`))return null;throw e}},v=l(f,t.build.os===`windows`),y=u(f,v,t.build.os===`windows`),b=t.stdin.isTerminal();return{argv:d,env:f,cwd:p,stdout:m,stderr:h,stdin:g,readStdin:()=>s(t,b),isTTY:t.stdout.isTerminal(),stdinIsTTY:b,exit:e=>t.exit(e),readFile:_,homedir:v,configDir:y}}function o(){return globalThis.Deno}async function s(e,t){if(t)return null;let n=e.stdin.readable.getReader(),r=new TextDecoder,i=[];try{for(;;){let{value:e,done:t}=await n.read();if(t){i.push(r.decode());break}i.push(r.decode(e,{stream:!0}))}}finally{n.releaseLock()}return i.join(``)}function c(e){let t=new TextDecoder,n=``,r=!1;return async()=>{let i=e.stdin.readable.getReader();try{for(;;){let e=n.indexOf(`
2
+ `);if(e!==-1){let t=n.slice(0,e).replace(/\r$/,``);return n=n.slice(e+1),t}if(r){if(n.length===0)return null;let e=n;return n=``,e}let{value:a,done:o}=await i.read();if(o){n+=t.decode(),r=!0;continue}n+=t.decode(a,{stream:!0})}}finally{i.releaseLock()}}}function l(e,n){return t(e,n)}function u(t,n,r){return e(t,r,n)}export{a as createDenoAdapter};