@kjanat/dreamcli 3.0.0-rc.1 → 3.0.0-rc.2

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 (136) hide show
  1. package/CHANGELOG.md +26 -1
  2. package/dist/core/cli/dispatch.mjs +214 -1
  3. package/dist/core/cli/help-links.mjs +41 -1
  4. package/dist/core/cli/index.mjs +901 -1
  5. package/dist/core/cli/planner.mjs +300 -1
  6. package/dist/core/cli/plugin.mjs +41 -1
  7. package/dist/core/cli/propagate.mjs +57 -1
  8. package/dist/core/cli/root-help.mjs +208 -4
  9. package/dist/core/cli/root-surface.mjs +27 -1
  10. package/dist/core/cli/runtime-preflight.mjs +168 -1
  11. package/dist/core/completion/index.mjs +90 -1
  12. package/dist/core/completion/shells/bash.mjs +304 -3
  13. package/dist/core/completion/shells/fish.mjs +159 -2
  14. package/dist/core/completion/shells/powershell.mjs +353 -2
  15. package/dist/core/completion/shells/shared.mjs +154 -1
  16. package/dist/core/completion/shells/zsh.mjs +244 -2
  17. package/dist/core/config/index.mjs +246 -1
  18. package/dist/core/config/package-json.mjs +385 -3
  19. package/dist/core/errors/index.mjs +87 -1
  20. package/dist/core/execution/index.mjs +189 -1
  21. package/dist/core/help/ansi.mjs +122 -2
  22. package/dist/core/help/index.mjs +329 -7
  23. package/dist/core/json-schema/index.mjs +487 -9
  24. package/dist/core/json-schema/meta-descriptions.generated.mjs +93 -28
  25. package/dist/core/output/activity.mjs +452 -1
  26. package/dist/core/output/bind.mjs +56 -1
  27. package/dist/core/output/contracts.mjs +57 -1
  28. package/dist/core/output/display-value.mjs +32 -1
  29. package/dist/core/output/index.d.mts +21 -0
  30. package/dist/core/output/index.mjs +442 -2
  31. package/dist/core/output/renderers.mjs +46 -1
  32. package/dist/core/output/writer.mjs +12 -1
  33. package/dist/core/parse/index.mjs +555 -1
  34. package/dist/core/prompt/index.d.mts +0 -1
  35. package/dist/core/prompt/index.mjs +348 -6
  36. package/dist/core/resolve/args.mjs +105 -1
  37. package/dist/core/resolve/coerce.mjs +279 -1
  38. package/dist/core/resolve/config.mjs +19 -1
  39. package/dist/core/resolve/errors.mjs +140 -2
  40. package/dist/core/resolve/flags.mjs +196 -1
  41. package/dist/core/resolve/index.mjs +85 -1
  42. package/dist/core/resolve/property.d.mts +0 -1
  43. package/dist/core/resolve/property.mjs +45 -1
  44. package/dist/core/schema/arg.mjs +463 -1
  45. package/dist/core/schema/command.d.mts +18 -0
  46. package/dist/core/schema/command.mjs +712 -1
  47. package/dist/core/schema/flag.mjs +453 -1
  48. package/dist/core/schema/middleware.mjs +41 -1
  49. package/dist/core/schema/number-constraints.mjs +60 -1
  50. package/dist/core/schema-dsl/runtime.mjs +271 -2
  51. package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
  52. package/dist/core/testkit/index.mjs +83 -1
  53. package/dist/index.d.mts +2 -1
  54. package/dist/index.mjs +22 -1
  55. package/dist/runtime/adapter.mjs +82 -1
  56. package/dist/runtime/auto.mjs +46 -1
  57. package/dist/runtime/bun.mjs +28 -1
  58. package/dist/runtime/deno.mjs +217 -2
  59. package/dist/runtime/detect.mjs +45 -1
  60. package/dist/runtime/node.mjs +169 -2
  61. package/dist/runtime/paths.mjs +48 -1
  62. package/dist/runtime.mjs +7 -1
  63. package/dist/strings.mjs +22 -1
  64. package/dist/testkit.mjs +5 -1
  65. package/dist/version.mjs +7 -1
  66. package/package.json +17 -26
  67. package/src/core/cli/dispatch.ts +0 -355
  68. package/src/core/cli/help-links.ts +0 -82
  69. package/src/core/cli/index.ts +0 -1614
  70. package/src/core/cli/planner.ts +0 -656
  71. package/src/core/cli/plugin.ts +0 -117
  72. package/src/core/cli/propagate.ts +0 -97
  73. package/src/core/cli/root-help.ts +0 -342
  74. package/src/core/cli/root-surface.ts +0 -87
  75. package/src/core/cli/runtime-preflight.ts +0 -456
  76. package/src/core/completion/index.ts +0 -138
  77. package/src/core/completion/shells/bash.ts +0 -459
  78. package/src/core/completion/shells/fish.ts +0 -259
  79. package/src/core/completion/shells/powershell.ts +0 -439
  80. package/src/core/completion/shells/shared.ts +0 -310
  81. package/src/core/completion/shells/zsh.ts +0 -381
  82. package/src/core/config/index.ts +0 -417
  83. package/src/core/config/package-json.ts +0 -560
  84. package/src/core/errors/index.ts +0 -193
  85. package/src/core/execution/index.ts +0 -265
  86. package/src/core/help/ansi.ts +0 -144
  87. package/src/core/help/index.ts +0 -563
  88. package/src/core/json-schema/index.ts +0 -910
  89. package/src/core/json-schema/meta-descriptions.generated.ts +0 -202
  90. package/src/core/output/activity.ts +0 -575
  91. package/src/core/output/bind.ts +0 -59
  92. package/src/core/output/contracts.ts +0 -194
  93. package/src/core/output/display-value.ts +0 -48
  94. package/src/core/output/index.ts +0 -704
  95. package/src/core/output/renderers.ts +0 -125
  96. package/src/core/output/writer.ts +0 -46
  97. package/src/core/parse/index.ts +0 -742
  98. package/src/core/prompt/index.ts +0 -623
  99. package/src/core/resolve/args.ts +0 -144
  100. package/src/core/resolve/coerce.ts +0 -500
  101. package/src/core/resolve/config.ts +0 -26
  102. package/src/core/resolve/contracts.ts +0 -135
  103. package/src/core/resolve/errors.ts +0 -227
  104. package/src/core/resolve/flags.ts +0 -269
  105. package/src/core/resolve/index.ts +0 -108
  106. package/src/core/resolve/property.ts +0 -99
  107. package/src/core/schema/activity.ts +0 -240
  108. package/src/core/schema/arg.ts +0 -841
  109. package/src/core/schema/command.ts +0 -1500
  110. package/src/core/schema/flag.ts +0 -917
  111. package/src/core/schema/index.ts +0 -96
  112. package/src/core/schema/middleware.ts +0 -171
  113. package/src/core/schema/number-constraints.ts +0 -153
  114. package/src/core/schema/prompt.ts +0 -171
  115. package/src/core/schema/run.ts +0 -198
  116. package/src/core/schema-dsl/index.ts +0 -109
  117. package/src/core/schema-dsl/parse.ts +0 -262
  118. package/src/core/schema-dsl/runtime.ts +0 -609
  119. package/src/core/schema-dsl/to-json-schema.ts +0 -102
  120. package/src/core/testkit/index.ts +0 -147
  121. package/src/index.ts +0 -181
  122. package/src/runtime/adapter.ts +0 -303
  123. package/src/runtime/auto.ts +0 -86
  124. package/src/runtime/bun.ts +0 -48
  125. package/src/runtime/deno.ts +0 -367
  126. package/src/runtime/detect.ts +0 -105
  127. package/src/runtime/index.ts +0 -21
  128. package/src/runtime/node-builtins.d.ts +0 -27
  129. package/src/runtime/node.ts +0 -289
  130. package/src/runtime/paths.ts +0 -64
  131. package/src/runtime/support.ts +0 -77
  132. package/src/runtime.ts +0 -31
  133. package/src/schema.ts +0 -16
  134. package/src/strings.ts +0 -34
  135. package/src/testkit.ts +0 -25
  136. package/src/version.ts +0 -20
@@ -1 +1,85 @@
1
- import{isValidationError as e}from"../errors/index.mjs";import{collectValidationErrors as t,isNonEmpty as n,throwAggregatedErrors as r}from"./errors.mjs";import{resolveArgs as i}from"./args.mjs";import{resolveFlags as a}from"./flags.mjs";async function o(o,s,c){let l=c?.stdinData,u=c?.env??{},d=c?.config??{},f=c?.prompter,p=[],m={},h={},g=[];try{m=await a(o.flags,s.flags,u,d,f,o.interactive,p)}catch(n){if(!e(n))throw n;g.push(...t(n))}try{h=i(o.args,s.args,l,u,p)}catch(n){if(!e(n))throw n;g.push(...t(n))}return n(g)&&r(g),{flags:m,args:h,deprecations:p}}export{o as resolve};
1
+ import { isValidationError } from "../errors/index.mjs";
2
+ import { collectValidationErrors, isNonEmpty, throwAggregatedErrors } from "./errors.mjs";
3
+ import { resolveArgs } from "./args.mjs";
4
+ import { resolveFlags } from "./flags.mjs";
5
+ //#region src/core/resolve/index.ts
6
+ /**
7
+ * Resolution chain: CLI -> env -> config -> prompt -> default.
8
+ *
9
+ * v0.1 implemented: **CLI parsed value -> default value**.
10
+ * v0.2 adds: **env variable resolution** and **config object resolution**
11
+ * between CLI and default.
12
+ * v0.3 adds: **prompt resolution** between config and default.
13
+ *
14
+ * The resolver takes raw {@linkcode ParseResult} (from the parser) and a
15
+ * {@linkcode CommandSchema}, applies the resolution chain, and validates
16
+ * that all required flags/args are present. On success it returns a
17
+ * {@linkcode ResolveResult} with fully resolved values; on failure it throws
18
+ * {@linkcode ValidationError}.
19
+ *
20
+ * @module dreamcli/core/resolve
21
+ */
22
+ /**
23
+ * Resolve parsed values against a command schema.
24
+ *
25
+ * Low-level API: most applications should rely on `cli().run()`, `.execute()`,
26
+ * or `runCommand()`, which already call {@linkcode resolve} at the right time.
27
+ * Reach for this function when testing precedence rules directly or building
28
+ * custom execution flows around {@linkcode CommandSchema}.
29
+ *
30
+ * Resolution order:
31
+ * 1. CLI parsed value (from {@linkcode ParseResult})
32
+ * 2. Env variable (from {@linkcode ResolveOptions.env}, if flag declares `envVar`)
33
+ * 3. Config value (from {@linkcode ResolveOptions.config}, if flag declares `configPath`)
34
+ * 4. Prompt (from {@linkcode ResolveOptions.prompter}, if flag declares `prompt`)
35
+ * 5. Default value (from schema)
36
+ *
37
+ * After resolution, validates that all required flags and args have
38
+ * a value. Collects **all** validation errors before throwing, so the
39
+ * user sees every missing field at once.
40
+ *
41
+ * @param schema - The command schema defining flags and args
42
+ * @param parsed - Raw parsed values from the parser
43
+ * @param options - External state for the resolution chain
44
+ * @returns Fully resolved flag and arg values
45
+ * @throws {@linkcode ValidationError} if any required flag or arg is missing,
46
+ * or if an env/config value fails coercion
47
+ *
48
+ * @example
49
+ * ```ts
50
+ * const parsed = parse(deploy.schema, ['production']);
51
+ * const resolved = await resolve(deploy.schema, parsed, {
52
+ * env: { DEPLOY_REGION: 'eu' },
53
+ * });
54
+ * ```
55
+ */
56
+ async function resolve(schema, parsed, options) {
57
+ const stdinData = options?.stdinData;
58
+ const env = options?.env ?? {};
59
+ const config = options?.config ?? {};
60
+ const prompter = options?.prompter;
61
+ const deprecations = [];
62
+ let flags = {};
63
+ let args = {};
64
+ const errors = [];
65
+ try {
66
+ flags = await resolveFlags(schema.flags, parsed.flags, env, config, prompter, schema.interactive, deprecations);
67
+ } catch (error) {
68
+ if (!isValidationError(error)) throw error;
69
+ errors.push(...collectValidationErrors(error));
70
+ }
71
+ try {
72
+ args = resolveArgs(schema.args, parsed.args, stdinData, env, deprecations);
73
+ } catch (error) {
74
+ if (!isValidationError(error)) throw error;
75
+ errors.push(...collectValidationErrors(error));
76
+ }
77
+ if (isNonEmpty(errors)) throwAggregatedErrors(errors);
78
+ return {
79
+ flags,
80
+ args,
81
+ deprecations
82
+ };
83
+ }
84
+ //#endregion
85
+ export { resolve };
@@ -1,7 +1,6 @@
1
1
  import { NumberConstraints } from "../schema/number-constraints.mjs";
2
2
  import { ArgSchema } from "../schema/arg.mjs";
3
3
  import { FlagSchema } from "../schema/flag.mjs";
4
-
5
4
  //#region src/core/resolve/property.d.ts
6
5
  /** Flag/arg kinds that share a common coercion path. */
7
6
  declare const SHARED_PROPERTY_MODEL_KINDS: readonly ['string', 'number', 'enum', 'custom'];
@@ -1 +1,45 @@
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
+ //#region src/core/resolve/property.ts
2
+ /** Extract the shared coercion slice from a flag schema, or `undefined` for boolean/array (handled separately). */
3
+ function toSharedFlagPropertySchema(schema) {
4
+ switch (schema.kind) {
5
+ case "string": return { kind: "string" };
6
+ case "number": return {
7
+ kind: "number",
8
+ numberConstraints: schema.numberConstraints
9
+ };
10
+ case "enum": return {
11
+ kind: "enum",
12
+ enumValues: schema.enumValues
13
+ };
14
+ case "custom": return schema.parseFn === void 0 ? { kind: "custom" } : {
15
+ kind: "custom",
16
+ parseFn: schema.parseFn
17
+ };
18
+ case "boolean":
19
+ case "array": return;
20
+ }
21
+ }
22
+ /** Extract the shared coercion slice from an arg schema (all arg kinds are shared). */
23
+ function toSharedArgPropertySchema(schema) {
24
+ switch (schema.kind) {
25
+ case "string": return { kind: "string" };
26
+ case "number": return {
27
+ kind: "number",
28
+ numberConstraints: schema.numberConstraints
29
+ };
30
+ case "enum": return {
31
+ kind: "enum",
32
+ enumValues: schema.enumValues
33
+ };
34
+ case "custom": {
35
+ if (schema.parseFn === void 0) return { kind: "custom" };
36
+ const parseFn = schema.parseFn;
37
+ return {
38
+ kind: "custom",
39
+ parseFn: (raw) => parseFn(typeof raw === "string" ? raw : String(raw))
40
+ };
41
+ }
42
+ }
43
+ }
44
+ //#endregion
45
+ export { toSharedArgPropertySchema, toSharedFlagPropertySchema };
@@ -1 +1,463 @@
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};
1
+ import { assertNumberConstraints } from "./number-constraints.mjs";
2
+ //#region src/core/schema/arg.ts
3
+ /**
4
+ * Positional argument schema builder with full type inference.
5
+ *
6
+ * Each factory (`arg.string()`, `arg.number()`, `arg.enum()`, `arg.custom()`) returns an
7
+ * immutable {@linkcode ArgBuilder} whose generic parameter tracks the value type,
8
+ * presence state, and variadic flag through the fluent chain.
9
+ *
10
+ * @module dreamcli/core/schema/arg
11
+ */
12
+ /**
13
+ * Create a raw {@link ArgSchema} object with sensible defaults.
14
+ *
15
+ * Most consumers should prefer the higher-level {@link arg} factory, which
16
+ * returns an immutable {@link ArgBuilder} with type inference and fluent
17
+ * modifiers. `createArgSchema()` exists for advanced schema composition,
18
+ * targeted tests, or custom builders that need the plain runtime descriptor.
19
+ *
20
+ * `overrides` are shallow-merged on top of the default shape, so callers are
21
+ * responsible for preserving invariants such as variadic ordering and
22
+ * compatible `parseFn` / `kind` combinations.
23
+ *
24
+ * @param kind - Discriminator for the value type this arg accepts.
25
+ * @param overrides - Partial schema fields shallow-merged onto defaults.
26
+ * @returns A fully populated {@link ArgSchema}.
27
+ *
28
+ * @example
29
+ * ```ts
30
+ * const schema = createArgSchema('custom', {
31
+ * description: 'Hex color',
32
+ * parseFn: (raw) => `#${raw}`,
33
+ * });
34
+ * ```
35
+ */
36
+ function createArgSchema(kind, overrides) {
37
+ return {
38
+ kind,
39
+ presence: "required",
40
+ variadic: false,
41
+ stdinMode: false,
42
+ defaultValue: void 0,
43
+ description: void 0,
44
+ envVar: void 0,
45
+ enumValues: void 0,
46
+ numberConstraints: void 0,
47
+ parseFn: void 0,
48
+ deprecated: void 0,
49
+ ...overrides
50
+ };
51
+ }
52
+ /**
53
+ * Immutable positional argument schema builder.
54
+ *
55
+ * The type parameter `C` is a phantom that tracks the value type, presence,
56
+ * and variadic state through the fluent chain. Each modifier returns a **new**
57
+ * builder — the original is never mutated.
58
+ *
59
+ * @example
60
+ * ```ts
61
+ * // Full command with multiple args and modifiers
62
+ * import { command, arg } from '@kjanat/dreamcli';
63
+ *
64
+ * command('deploy')
65
+ * .arg('target', arg.string()
66
+ * .env('DEPLOY_TARGET')
67
+ * .describe('Deploy target'))
68
+ * .arg('port', arg.number()
69
+ * .env('PORT')
70
+ * .default(3000)
71
+ * .describe('Port number'))
72
+ * .arg('files', arg.string()
73
+ * .variadic()
74
+ * .optional()
75
+ * .describe('Extra config files'))
76
+ * .action(({ args }) => {
77
+ * args.target; // string (required, from CLI or $DEPLOY_TARGET)
78
+ * args.port; // number (defaulted, from CLI, $PORT, or 3000)
79
+ * args.files; // string[] (optional variadic)
80
+ * });
81
+ * ```
82
+ *
83
+ * @example
84
+ * ```ts
85
+ * // Type inference
86
+ * const target = arg.string();
87
+ * type T = InferArg<typeof target>; // string
88
+ *
89
+ * const opt = arg.string().optional();
90
+ * type O = InferArg<typeof opt>; // string | undefined
91
+ *
92
+ * const files = arg.string().variadic();
93
+ * type F = InferArg<typeof files>; // string[]
94
+ * ```
95
+ */
96
+ var ArgBuilder = class ArgBuilder {
97
+ /** @internal Runtime schema descriptor. */
98
+ schema;
99
+ /**
100
+ * Create an arg builder from a pre-built schema descriptor.
101
+ *
102
+ * @param schema - Runtime descriptor for this positional argument.
103
+ */
104
+ constructor(schema) {
105
+ this.schema = schema;
106
+ }
107
+ /**
108
+ * Mark the arg as required (this is the default for positional args).
109
+ * Produces an error if no value resolves from any configured source
110
+ * (CLI → stdin → env → default).
111
+ *
112
+ * @example
113
+ * ```ts
114
+ * arg.string().required() // explicit, same as default
115
+ *
116
+ * // In a command — omitting <target> causes a ValidationError:
117
+ * command('deploy')
118
+ * .arg('target', arg.string().required().describe('Deploy target'))
119
+ * // $ mycli deploy
120
+ * // Error: Missing required argument <target>
121
+ * ```
122
+ *
123
+ * @returns The builder (for chaining).
124
+ */
125
+ required() {
126
+ return new ArgBuilder({
127
+ ...this.schema,
128
+ presence: "required"
129
+ });
130
+ }
131
+ /**
132
+ * Mark the arg as optional. Handlers receive `undefined` when absent.
133
+ *
134
+ * @example
135
+ * ```ts
136
+ * arg.string().optional()
137
+ *
138
+ * // In a command — handler receives `undefined` when omitted:
139
+ * command('greet')
140
+ * .arg('name', arg.string().optional().describe('Who to greet'))
141
+ * .action(({ args }) => {
142
+ * args.name; // string | undefined
143
+ * });
144
+ * // $ mycli greet → args.name is undefined
145
+ * // $ mycli greet Alice → args.name is 'Alice'
146
+ * ```
147
+ *
148
+ * @returns The builder (for chaining).
149
+ */
150
+ optional() {
151
+ return new ArgBuilder({
152
+ ...this.schema,
153
+ presence: "optional"
154
+ });
155
+ }
156
+ /**
157
+ * Provide a default value. The arg becomes "always present" — handlers
158
+ * will never see `undefined`.
159
+ *
160
+ * The generic constraint `V extends C['valueType']` ensures the default
161
+ * matches the arg's declared type.
162
+ *
163
+ * Resolution order when extra sources are configured: CLI → stdin → env → **default**.
164
+ *
165
+ * @param value - Fallback used when no CLI value or env var resolves.
166
+ * @returns The builder (for chaining).
167
+ *
168
+ * @example
169
+ * ```ts
170
+ * arg.string().default('production')
171
+ * arg.number().default(3000)
172
+ *
173
+ * // In a command — default kicks in when CLI and env are both absent:
174
+ * command('deploy')
175
+ * .arg('env', arg.string()
176
+ * .env('DEPLOY_ENV')
177
+ * .default('staging')
178
+ * .describe('Target environment'))
179
+ * .action(({ args }) => {
180
+ * args.env; // string (never undefined)
181
+ * });
182
+ * // $ mycli deploy → 'staging' (default)
183
+ * // $ DEPLOY_ENV=prod mycli deploy → 'prod' (env)
184
+ * // $ mycli deploy production → 'production' (CLI)
185
+ * ```
186
+ */
187
+ default(value) {
188
+ return new ArgBuilder({
189
+ ...this.schema,
190
+ presence: "defaulted",
191
+ defaultValue: value
192
+ });
193
+ }
194
+ /**
195
+ * Mark this arg as variadic — it consumes all remaining positional
196
+ * arguments. The inferred type becomes `T[]`.
197
+ *
198
+ * A variadic arg must be the last positional in a command.
199
+ *
200
+ * @example
201
+ * ```ts
202
+ * arg.string().variadic()
203
+ *
204
+ * // In a command — collects all remaining positionals:
205
+ * command('build')
206
+ * .arg('entry', arg.string().describe('Main entry'))
207
+ * .arg('extras', arg.string().variadic().optional().describe('Extra files'))
208
+ * .action(({ args }) => {
209
+ * args.entry; // string
210
+ * args.extras; // string[]
211
+ * });
212
+ * // $ mycli build main.ts a.ts b.ts
213
+ * // → entry = 'main.ts', extras = ['a.ts', 'b.ts']
214
+ * ```
215
+ *
216
+ * @returns The builder (for chaining).
217
+ */
218
+ variadic() {
219
+ return new ArgBuilder({
220
+ ...this.schema,
221
+ variadic: true
222
+ });
223
+ }
224
+ /**
225
+ * Allow this arg to resolve from stdin when CLI input is missing.
226
+ *
227
+ * Resolution order becomes: CLI value -> stdin -> env -> default.
228
+ * Only one arg per command may enable stdin mode.
229
+ *
230
+ * @returns The builder (for chaining).
231
+ *
232
+ * @example
233
+ * ```ts
234
+ * arg.string().describe('Input text').stdin()
235
+ * // $ echo "hello" | mycli transform → input = 'hello' (from stdin)
236
+ * // $ mycli transform "hello" → input = 'hello' (from CLI)
237
+ * ```
238
+ */
239
+ stdin() {
240
+ return new ArgBuilder({
241
+ ...this.schema,
242
+ stdinMode: true
243
+ });
244
+ }
245
+ /**
246
+ * Bind to an environment variable.
247
+ *
248
+ * When the arg is not provided on the CLI, the resolver checks this
249
+ * env var before falling back to the default value. The env string is
250
+ * coerced to the arg's declared kind (passthrough for strings, parsed
251
+ * for numbers, run through `parseFn` for custom args).
252
+ *
253
+ * Resolution order when extra sources are configured: **CLI → stdin → env → default**.
254
+ *
255
+ * Help output shows `[env: VAR]` next to the arg description.
256
+ *
257
+ * @param varName - Environment variable name (e.g. `'DEPLOY_TARGET'`).
258
+ * @returns The builder (for chaining).
259
+ *
260
+ * @example
261
+ * ```ts
262
+ * command('deploy')
263
+ * .arg('target', arg.string().env('DEPLOY_TARGET').describe('Deploy target'))
264
+ * .arg('port', arg.number().env('PORT').default(3000))
265
+ * .action(({ args }) => {
266
+ * console.log(args.target); // from CLI, $DEPLOY_TARGET, or error
267
+ * console.log(args.port); // from CLI, $PORT, or 3000
268
+ * });
269
+ * ```
270
+ */
271
+ env(varName) {
272
+ return new ArgBuilder({
273
+ ...this.schema,
274
+ envVar: varName
275
+ });
276
+ }
277
+ /**
278
+ * Human-readable description shown in help output.
279
+ *
280
+ * @param description - Text displayed next to the arg in `--help`.
281
+ * @returns The builder (for chaining).
282
+ *
283
+ * @example
284
+ * ```ts
285
+ * arg.string().describe('Deploy target')
286
+ *
287
+ * // Help output:
288
+ * // Arguments:
289
+ * // <target> Deploy target
290
+ * ```
291
+ */
292
+ describe(description) {
293
+ return new ArgBuilder({
294
+ ...this.schema,
295
+ description
296
+ });
297
+ }
298
+ /**
299
+ * Mark this arg as deprecated.
300
+ *
301
+ * When used, a warning is emitted to stderr. Help text shows
302
+ * `[deprecated]` or `[deprecated: <reason>]`.
303
+ *
304
+ * Does not change the arg's type-level config — it's metadata only.
305
+ *
306
+ * @param message - Optional migration reason/guidance.
307
+ * @returns The builder (for chaining).
308
+ *
309
+ * @example
310
+ * ```ts
311
+ * arg.string().deprecated() // generic
312
+ * arg.string().deprecated('use --target flag instead') // with guidance
313
+ *
314
+ * // Help output:
315
+ * // Arguments:
316
+ * // <target> Deploy target [deprecated: use --target flag instead]
317
+ * ```
318
+ */
319
+ deprecated(message) {
320
+ return new ArgBuilder({
321
+ ...this.schema,
322
+ deprecated: message ?? true
323
+ });
324
+ }
325
+ /**
326
+ * Require an integer value. Composes with other numeric constraints.
327
+ *
328
+ * @param value - Whether to require an integer.
329
+ * @defaultValue `true`
330
+ * @returns The builder (for chaining).
331
+ *
332
+ * @example
333
+ * ```ts
334
+ * arg.number().int() // rejects 3.7, accepts 3
335
+ * arg.number({ int: true }).int(false) // re-allows non-integers
336
+ * ```
337
+ */
338
+ int(value = true) {
339
+ return new ArgBuilder({
340
+ ...this.schema,
341
+ numberConstraints: {
342
+ ...this.schema.numberConstraints,
343
+ int: value
344
+ }
345
+ });
346
+ }
347
+ /**
348
+ * Set an inclusive lower bound. Composes with other numeric constraints;
349
+ * a later call overrides an earlier `min` (including one from the options
350
+ * object).
351
+ *
352
+ * @param value - Inclusive minimum.
353
+ * @returns The builder (for chaining).
354
+ *
355
+ * @example
356
+ * ```ts
357
+ * arg.number().min(0) // rejects -1, accepts 0
358
+ * arg.number({ min: 0 }).min(5) // effective min is 5
359
+ * ```
360
+ */
361
+ min(value) {
362
+ const numberConstraints = {
363
+ ...this.schema.numberConstraints,
364
+ min: value
365
+ };
366
+ assertNumberConstraints(numberConstraints);
367
+ return new ArgBuilder({
368
+ ...this.schema,
369
+ numberConstraints
370
+ });
371
+ }
372
+ /**
373
+ * Set an inclusive upper bound. Composes with other numeric constraints;
374
+ * a later call overrides an earlier `max`.
375
+ *
376
+ * @param value - Inclusive maximum.
377
+ * @returns The builder (for chaining).
378
+ *
379
+ * @example
380
+ * ```ts
381
+ * arg.number().max(100) // rejects 101, accepts 100
382
+ * ```
383
+ */
384
+ max(value) {
385
+ const numberConstraints = {
386
+ ...this.schema.numberConstraints,
387
+ max: value
388
+ };
389
+ assertNumberConstraints(numberConstraints);
390
+ return new ArgBuilder({
391
+ ...this.schema,
392
+ numberConstraints
393
+ });
394
+ }
395
+ /**
396
+ * Require (or, with `false`, allow) a finite value. Finiteness is enforced
397
+ * by default, so this is mainly used as `.finite(false)` to re-allow
398
+ * `Infinity` / `-Infinity`.
399
+ *
400
+ * @param allow - Whether to require a finite value.
401
+ * @defaultValue `true`
402
+ * @returns The builder (for chaining).
403
+ *
404
+ * @example
405
+ * ```ts
406
+ * arg.number().finite(false) // accepts Infinity
407
+ * ```
408
+ */
409
+ finite(allow = true) {
410
+ return new ArgBuilder({
411
+ ...this.schema,
412
+ numberConstraints: {
413
+ ...this.schema.numberConstraints,
414
+ finite: allow
415
+ }
416
+ });
417
+ }
418
+ };
419
+ /**
420
+ * Positional argument schema factory.
421
+ *
422
+ * Entry point for defining args on a command. Use `arg.<kind>()` to create
423
+ * an {@linkcode ArgBuilder}, then chain modifiers and pass the result to
424
+ * `command().arg(name, builder)`.
425
+ *
426
+ * Four kinds are available:
427
+ * - `arg.string()` — raw string (most common)
428
+ * - `arg.number()` — parsed to number, errors on NaN
429
+ * - `arg.enum(values)` — constrained to listed literals
430
+ * - `arg.custom(fn)` — arbitrary parse function, infers return type
431
+ *
432
+ * @example
433
+ * ```ts
434
+ * import { command, arg } from '@kjanat/dreamcli';
435
+ *
436
+ * command('deploy')
437
+ * .arg('target', arg.string().env('DEPLOY_TARGET').describe('Where to deploy'))
438
+ * .arg('port', arg.number().env('PORT').default(3000))
439
+ * .action(({ args }) => {
440
+ * console.log(`Deploying to ${args.target} on port ${args.port}`);
441
+ * });
442
+ *
443
+ * // $ mycli deploy production 8080 → target='production', port=8080
444
+ * // $ DEPLOY_TARGET=staging mycli deploy → target='staging', port=3000
445
+ * ```
446
+ */
447
+ const arg = {
448
+ string() {
449
+ return new ArgBuilder(createArgSchema("string"));
450
+ },
451
+ number(constraints) {
452
+ if (constraints !== void 0) assertNumberConstraints(constraints);
453
+ return new ArgBuilder(createArgSchema("number", constraints !== void 0 ? { numberConstraints: constraints } : {}));
454
+ },
455
+ enum(values) {
456
+ return new ArgBuilder(createArgSchema("enum", { enumValues: values }));
457
+ },
458
+ custom(parseFn) {
459
+ return new ArgBuilder(createArgSchema("custom", { parseFn }));
460
+ }
461
+ };
462
+ //#endregion
463
+ export { ArgBuilder, arg, createArgSchema };
@@ -4,6 +4,7 @@ import { PromptConfig } from "./prompt.mjs";
4
4
  import { FlagBuilder, FlagConfig, FlagSchema, InferFlags } from "./flag.mjs";
5
5
  import { ErasedMiddlewareHandler, Middleware } from "./middleware.mjs";
6
6
  import { RunOptions, RunResult } from "./run.mjs";
7
+ import { Colors } from "ansispeck";
7
8
 
8
9
  //#region src/core/schema/command.d.ts
9
10
  /**
@@ -152,6 +153,23 @@ interface Out {
152
153
  * decorative output should be suppressed regardless of `isTTY`.
153
154
  */
154
155
  readonly isTTY: boolean;
156
+ /**
157
+ * Context-aware ANSI color palette (powered by `ansispeck`).
158
+ *
159
+ * Colors are enabled only when stdout is a TTY, JSON mode is off, and the
160
+ * environment supports color (`NO_COLOR`, `FORCE_COLOR`, `--no-color`,
161
+ * `--color`, `CI` are respected). When disabled, every formatter is an
162
+ * identity function — `out.color.red('x')` returns `'x'` — so handlers can
163
+ * style unconditionally without gating on `isTTY`/`jsonMode` themselves.
164
+ *
165
+ * @example
166
+ * ```ts
167
+ * .action(({ out }) => {
168
+ * out.log(`${out.color.green('✔')} deployed ${out.color.bold('api')}`);
169
+ * });
170
+ * ```
171
+ */
172
+ readonly color: Colors;
155
173
  /**
156
174
  * Render tabular data.
157
175
  *