@kjanat/dreamcli 4.0.0-rc.3 → 4.0.0

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 (212) hide show
  1. package/README.md +5 -7
  2. package/dist/{runtime/adapter.d.mts → adapter-D0hbBNVB.d.mts} +2 -4
  3. package/dist/completion-D4mz6axB.mjs +6 -0
  4. package/dist/completion.d.mts +90 -0
  5. package/dist/completion.mjs +1 -0
  6. package/dist/config-B9ddC-Kb.mjs +1 -0
  7. package/dist/config.d.mts +2 -0
  8. package/dist/config.mjs +1 -0
  9. package/dist/core-Cp2w8vRq.mjs +17 -0
  10. package/dist/index-BziI2aKc.d.mts +5440 -0
  11. package/dist/index-DOfClfYR.d.mts +370 -0
  12. package/dist/index-DWsnGZlx.d.mts +831 -0
  13. package/dist/{core/cli/index.d.mts → index-DXROeDPC.d.mts} +116 -57
  14. package/dist/index-DndPmT8J.d.mts +275 -0
  15. package/dist/{core/json-schema/index.d.mts → index-DyoaS234.d.mts} +43 -34
  16. package/dist/index.d.mts +190 -41
  17. package/dist/index.mjs +1 -26
  18. package/dist/json-schema-C9SzZ7jY.mjs +52 -0
  19. package/dist/json-schema.d.mts +2 -0
  20. package/dist/json-schema.mjs +1 -0
  21. package/dist/package-json-BgE9YjjQ.mjs +3 -0
  22. package/dist/prompt.d.mts +48 -0
  23. package/dist/prompt.mjs +1 -0
  24. package/dist/rolldown-runtime-G4Kt5YOX.mjs +1 -0
  25. package/dist/runtime.d.mts +2 -6
  26. package/dist/runtime.mjs +1 -6
  27. package/dist/terminal-C8KTXjv5.mjs +6 -0
  28. package/dist/test-prompter-v__jT2yG.mjs +1 -0
  29. package/dist/testkit.d.mts +54 -6
  30. package/dist/testkit.mjs +1 -5
  31. package/dist/version.mjs +1 -7
  32. package/dreamcli.schema.json +697 -538
  33. package/package.json +29 -7
  34. package/skills/cli-creation/SKILL.md +16 -11
  35. package/CHANGELOG.md +0 -1116
  36. package/dist/core/cli/builtins.d.mts +0 -117
  37. package/dist/core/cli/builtins.mjs +0 -135
  38. package/dist/core/cli/compiled.d.mts +0 -66
  39. package/dist/core/cli/compiled.mjs +0 -76
  40. package/dist/core/cli/dispatch.d.mts +0 -115
  41. package/dist/core/cli/dispatch.mjs +0 -205
  42. package/dist/core/cli/help-links.d.mts +0 -27
  43. package/dist/core/cli/help-links.mjs +0 -41
  44. package/dist/core/cli/index.mjs +0 -1271
  45. package/dist/core/cli/planner.d.mts +0 -174
  46. package/dist/core/cli/planner.mjs +0 -323
  47. package/dist/core/cli/plugin.d.mts +0 -94
  48. package/dist/core/cli/plugin.mjs +0 -41
  49. package/dist/core/cli/propagate.d.mts +0 -39
  50. package/dist/core/cli/propagate.mjs +0 -57
  51. package/dist/core/cli/reserved-flags.d.mts +0 -19
  52. package/dist/core/cli/reserved-flags.mjs +0 -158
  53. package/dist/core/cli/root-help.d.mts +0 -53
  54. package/dist/core/cli/root-help.mjs +0 -221
  55. package/dist/core/cli/root-output-flags.d.mts +0 -74
  56. package/dist/core/cli/root-output-flags.mjs +0 -169
  57. package/dist/core/cli/root-surface.d.mts +0 -64
  58. package/dist/core/cli/root-surface.mjs +0 -28
  59. package/dist/core/cli/runtime-preflight.d.mts +0 -213
  60. package/dist/core/cli/runtime-preflight.mjs +0 -221
  61. package/dist/core/completion/index.d.mts +0 -76
  62. package/dist/core/completion/index.mjs +0 -90
  63. package/dist/core/completion/shells/bash.d.mts +0 -23
  64. package/dist/core/completion/shells/bash.mjs +0 -312
  65. package/dist/core/completion/shells/fish.d.mts +0 -19
  66. package/dist/core/completion/shells/fish.mjs +0 -164
  67. package/dist/core/completion/shells/powershell.d.mts +0 -13
  68. package/dist/core/completion/shells/powershell.mjs +0 -360
  69. package/dist/core/completion/shells/shared.d.mts +0 -164
  70. package/dist/core/completion/shells/shared.mjs +0 -147
  71. package/dist/core/completion/shells/zsh.d.mts +0 -23
  72. package/dist/core/completion/shells/zsh.mjs +0 -256
  73. package/dist/core/config/index.d.mts +0 -191
  74. package/dist/core/config/index.mjs +0 -285
  75. package/dist/core/config/package-json.d.mts +0 -179
  76. package/dist/core/config/package-json.mjs +0 -353
  77. package/dist/core/errors/index.d.mts +0 -125
  78. package/dist/core/errors/index.mjs +0 -87
  79. package/dist/core/execution/index.d.mts +0 -61
  80. package/dist/core/execution/index.mjs +0 -220
  81. package/dist/core/help/ansi.d.mts +0 -84
  82. package/dist/core/help/ansi.mjs +0 -121
  83. package/dist/core/help/index.d.mts +0 -149
  84. package/dist/core/help/index.mjs +0 -418
  85. package/dist/core/help/theme.d.mts +0 -86
  86. package/dist/core/help/theme.mjs +0 -69
  87. package/dist/core/json-schema/index.mjs +0 -1008
  88. package/dist/core/json-schema/meta-descriptions.generated.d.mts +0 -274
  89. package/dist/core/json-schema/meta-descriptions.generated.mjs +0 -136
  90. package/dist/core/output/activity.d.mts +0 -193
  91. package/dist/core/output/activity.mjs +0 -452
  92. package/dist/core/output/bind.d.mts +0 -37
  93. package/dist/core/output/bind.mjs +0 -56
  94. package/dist/core/output/contracts.d.mts +0 -82
  95. package/dist/core/output/contracts.mjs +0 -57
  96. package/dist/core/output/display-value.d.mts +0 -19
  97. package/dist/core/output/display-value.mjs +0 -32
  98. package/dist/core/output/index.d.mts +0 -344
  99. package/dist/core/output/index.mjs +0 -514
  100. package/dist/core/output/renderers.d.mts +0 -45
  101. package/dist/core/output/renderers.mjs +0 -46
  102. package/dist/core/output/writer.d.mts +0 -39
  103. package/dist/core/output/writer.mjs +0 -12
  104. package/dist/core/parse/index.d.mts +0 -178
  105. package/dist/core/parse/index.mjs +0 -850
  106. package/dist/core/parse/occurrences.d.mts +0 -90
  107. package/dist/core/parse/occurrences.mjs +0 -114
  108. package/dist/core/prompt/index.d.mts +0 -213
  109. package/dist/core/prompt/index.mjs +0 -348
  110. package/dist/core/read-flags/index.d.mts +0 -150
  111. package/dist/core/read-flags/index.mjs +0 -217
  112. package/dist/core/resolve/args.d.mts +0 -39
  113. package/dist/core/resolve/args.mjs +0 -182
  114. package/dist/core/resolve/coerce.d.mts +0 -79
  115. package/dist/core/resolve/coerce.mjs +0 -900
  116. package/dist/core/resolve/config.d.mts +0 -10
  117. package/dist/core/resolve/config.mjs +0 -19
  118. package/dist/core/resolve/contracts.d.mts +0 -146
  119. package/dist/core/resolve/errors.d.mts +0 -10
  120. package/dist/core/resolve/errors.mjs +0 -148
  121. package/dist/core/resolve/flags.d.mts +0 -74
  122. package/dist/core/resolve/flags.mjs +0 -246
  123. package/dist/core/resolve/index.d.mts +0 -44
  124. package/dist/core/resolve/index.mjs +0 -123
  125. package/dist/core/resolve/path-checks.d.mts +0 -48
  126. package/dist/core/resolve/path-checks.mjs +0 -102
  127. package/dist/core/resolve/redaction.d.mts +0 -13
  128. package/dist/core/resolve/redaction.mjs +0 -14
  129. package/dist/core/resolve/stages.d.mts +0 -86
  130. package/dist/core/resolve/stages.mjs +0 -170
  131. package/dist/core/resolve/standard.d.mts +0 -26
  132. package/dist/core/resolve/standard.mjs +0 -212
  133. package/dist/core/schema/activity.d.mts +0 -189
  134. package/dist/core/schema/arg.d.mts +0 -1461
  135. package/dist/core/schema/arg.mjs +0 -1139
  136. package/dist/core/schema/brand.d.mts +0 -17
  137. package/dist/core/schema/cardinality.d.mts +0 -302
  138. package/dist/core/schema/cardinality.mjs +0 -514
  139. package/dist/core/schema/command.d.mts +0 -1132
  140. package/dist/core/schema/command.mjs +0 -999
  141. package/dist/core/schema/flag.d.mts +0 -1495
  142. package/dist/core/schema/flag.mjs +0 -1207
  143. package/dist/core/schema/index.d.mts +0 -15
  144. package/dist/core/schema/index.mjs +0 -10
  145. package/dist/core/schema/middleware.d.mts +0 -129
  146. package/dist/core/schema/middleware.mjs +0 -41
  147. package/dist/core/schema/number-constraints.d.mts +0 -96
  148. package/dist/core/schema/number-constraints.mjs +0 -60
  149. package/dist/core/schema/prompt.d.mts +0 -135
  150. package/dist/core/schema/provenance.d.mts +0 -99
  151. package/dist/core/schema/provenance.mjs +0 -28
  152. package/dist/core/schema/run.d.mts +0 -211
  153. package/dist/core/schema/source.d.mts +0 -180
  154. package/dist/core/schema/source.mjs +0 -206
  155. package/dist/core/schema/standard.d.mts +0 -100
  156. package/dist/core/schema/standard.mjs +0 -15
  157. package/dist/core/schema/stdin.d.mts +0 -97
  158. package/dist/core/schema/stdin.mjs +0 -91
  159. package/dist/core/schema/string-constraints.d.mts +0 -108
  160. package/dist/core/schema/string-constraints.mjs +0 -86
  161. package/dist/core/schema/value-parsers.d.mts +0 -150
  162. package/dist/core/schema/value-parsers.mjs +0 -160
  163. package/dist/core/schema/value.d.mts +0 -243
  164. package/dist/core/schema/value.mjs +0 -573
  165. package/dist/core/testkit/index.d.mts +0 -63
  166. package/dist/core/testkit/index.mjs +0 -102
  167. package/dist/runtime/adapter.mjs +0 -92
  168. package/dist/runtime/auto.d.mts +0 -25
  169. package/dist/runtime/auto.mjs +0 -45
  170. package/dist/runtime/deno.d.mts +0 -99
  171. package/dist/runtime/deno.mjs +0 -265
  172. package/dist/runtime/detect.d.mts +0 -86
  173. package/dist/runtime/detect.mjs +0 -45
  174. package/dist/runtime/index.d.mts +0 -6
  175. package/dist/runtime/node.d.mts +0 -71
  176. package/dist/runtime/node.mjs +0 -228
  177. package/dist/runtime/paths.d.mts +0 -31
  178. package/dist/runtime/paths.mjs +0 -48
  179. package/dist/strings.d.mts +0 -27
  180. package/dist/strings.mjs +0 -22
  181. package/examples/basic.ts +0 -37
  182. package/examples/flag-types.ts +0 -79
  183. package/examples/gh/package.json +0 -45
  184. package/examples/gh/src/commands/auth.ts +0 -66
  185. package/examples/gh/src/commands/issue.ts +0 -120
  186. package/examples/gh/src/commands/pr.ts +0 -125
  187. package/examples/gh/src/data/issues.yaml +0 -5
  188. package/examples/gh/src/data/issues.yaml.d.ts +0 -17
  189. package/examples/gh/src/data/pull-requests.yaml +0 -7
  190. package/examples/gh/src/data/pull-requests.yaml.d.ts +0 -18
  191. package/examples/gh/src/docs.ts +0 -11
  192. package/examples/gh/src/lib/auth.ts +0 -37
  193. package/examples/gh/src/lib/utils.ts +0 -17
  194. package/examples/gh/src/main.test.ts +0 -307
  195. package/examples/gh/src/main.ts +0 -46
  196. package/examples/help-config.ts +0 -43
  197. package/examples/interactive.ts +0 -67
  198. package/examples/json-mode.ts +0 -95
  199. package/examples/middleware.ts +0 -71
  200. package/examples/multi-command.ts +0 -66
  201. package/examples/output-extras.ts +0 -46
  202. package/examples/parser-control.ts +0 -40
  203. package/examples/pwsh-demo/README.md +0 -40
  204. package/examples/pwsh-demo/package.json +0 -41
  205. package/examples/pwsh-demo/pwsh-demo.cmd +0 -3
  206. package/examples/pwsh-demo/smoke-powershell.ps1 +0 -218
  207. package/examples/pwsh-demo/src/main.test.ts +0 -45
  208. package/examples/pwsh-demo/src/main.ts +0 -140
  209. package/examples/spinner-progress.ts +0 -49
  210. package/examples/standard-schema.ts +0 -45
  211. package/examples/testing.ts +0 -147
  212. package/examples/transport-launcher.ts +0 -85
@@ -1,240 +1,107 @@
1
1
  {
2
- "$schema": "https://json-schema.org/draft/2020-12/schema",
3
2
  "$id": "https://dreamcli.kjanat.dev/schemas/definition/v1.schema.json",
4
- "title": "@kjanat/dreamcli definition schema",
5
- "description": "Runtime descriptor for the CLI program.\n\nStores the program name, version, description, and registered command schemas.\\\nSealed by createCLISchema and rebuilt by each CLIBuilder step.",
6
- "type": "object",
7
- "additionalProperties": false,
8
- "properties": {
9
- "$schema": {
10
- "const": "https://dreamcli.kjanat.dev/schemas/definition/v1.schema.json"
11
- },
12
- "schemaVersion": {
13
- "const": 1
14
- },
15
- "name": {
16
- "type": "string",
17
- "description": "Program name (used in help text, usage lines, and completion scripts)."
18
- },
19
- "version": {
20
- "type": "string",
21
- "description": "Program version (shown by `--version`)."
22
- },
23
- "description": {
24
- "type": "string",
25
- "description": "Program description (shown in root help)."
26
- },
27
- "defaultCommand": {
28
- "$ref": "#/$defs/command",
29
- "description": "Schema of the default command dispatched when no subcommand matches.\n\nWhen set, the CLI root behaves like a hybrid command group: subcommands\ndispatch by name as usual, but empty argv or flags-only argv falls\nthrough to this command instead of showing root help.\n\nSet via the .default() builder method\nor the `defaultCommand` field of CLIDefinition."
30
- },
31
- "commands": {
32
- "type": "array",
33
- "items": {
34
- "$ref": "#/$defs/command"
35
- },
36
- "description": "Schemas of the registered commands, in registration order."
37
- }
38
- },
39
- "required": [
40
- "$schema",
41
- "schemaVersion",
42
- "name",
43
- "commands"
44
- ],
3
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
45
4
  "$defs": {
46
- "command": {
5
+ "arg": {
6
+ "description": "The runtime descriptor stored inside every ArgBuilder. Consumers (parser,\nhelp generator) read this to understand the arg's shape without touching\ngenerics.",
47
7
  "type": "object",
48
- "additionalProperties": false,
49
- "properties": {
50
- "name": {
51
- "type": "string",
52
- "description": "The command name (used for dispatch, e.g. `'deploy'`)."
53
- },
54
- "description": {
55
- "type": "string",
56
- "description": "Human-readable description for help text."
57
- },
58
- "aliases": {
59
- "type": "array",
60
- "items": {
61
- "type": "string"
62
- },
63
- "description": "Alternative names for this command."
64
- },
65
- "hidden": {
66
- "const": true,
67
- "description": "Whether this command is hidden from help listings."
68
- },
69
- "examples": {
70
- "type": "array",
71
- "items": {
72
- "$ref": "#/$defs/example"
73
- },
74
- "description": "Usage examples for help text."
75
- },
76
- "flags": {
77
- "type": "object",
78
- "additionalProperties": {
79
- "$ref": "#/$defs/flag"
80
- },
81
- "description": "Named flag schemas, keyed by flag name."
82
- },
83
- "args": {
84
- "type": "array",
85
- "items": {
86
- "$ref": "#/$defs/arg"
87
- },
88
- "description": "Ordered positional arg entries (name + schema)."
89
- },
90
- "commands": {
91
- "type": "array",
92
- "items": {
93
- "$ref": "#/$defs/command"
94
- },
95
- "description": "Nested subcommand schemas (for help rendering and completion).\n\nPure data — no execution closures. Populated by `.command()` on\n`CommandBuilder`. Empty for leaf commands."
96
- }
97
- },
98
8
  "required": [
9
+ "kind",
99
10
  "name",
100
- "flags",
101
- "args",
102
- "commands"
11
+ "presence"
103
12
  ],
104
- "description": "Runtime descriptor produced by CommandBuilder.\n\nConsumers (parser, help generator, CLI dispatcher) read this to\nunderstand the command's shape — flags, args, aliases, subcommands,\nand interactive resolver."
105
- },
106
- "commandDocument": {
107
- "type": "object",
108
- "additionalProperties": false,
109
13
  "properties": {
110
- "schemaVersion": {
111
- "const": 1,
112
- "description": "Version of the definition document format emitted by generateSchema\nand generateCommandSchema."
14
+ "configPath": {
15
+ "description": "Dotted config path for config resolution (e.g. `'deploy.region'`).",
16
+ "type": "string"
113
17
  },
114
- "name": {
115
- "type": "string",
116
- "description": "The command name used for dispatch."
18
+ "defaultDescription": {
19
+ "description": "Human-readable replacement for the default value in help, or `false` to\nomit the default annotation.",
20
+ "oneOf": [
21
+ {
22
+ "type": "string"
23
+ },
24
+ {
25
+ "const": false
26
+ }
27
+ ]
117
28
  },
118
- "description": {
119
- "type": "string",
120
- "description": "Human-readable description for help text."
29
+ "defaultValue": {
30
+ "description": "Runtime default value (if any)."
121
31
  },
122
- "aliases": {
123
- "type": "array",
124
- "items": {
125
- "type": "string"
126
- },
127
- "description": "Alternative names accepted for this command."
32
+ "deprecated": {
33
+ "description": "Deprecation marker.\n\n- `undefined` — not deprecated (default)\n- `true` — deprecated with no migration message\n- `string` — deprecated with a reason/migration message\n\nWhen a deprecated arg is used, a warning is emitted to stderr.\nHelp text shows `[deprecated]` or `[deprecated: <reason>]`.",
34
+ "oneOf": [
35
+ {
36
+ "type": "string"
37
+ },
38
+ {
39
+ "const": true
40
+ }
41
+ ]
128
42
  },
129
- "hidden": {
130
- "const": true,
131
- "description": "Whether the command is omitted from help listings."
43
+ "description": {
44
+ "description": "Human-readable description for help text.",
45
+ "type": "string"
132
46
  },
133
- "examples": {
134
- "type": "array",
135
- "items": {
136
- "$ref": "#/$defs/example"
137
- },
138
- "description": "Usage examples attached to the command."
47
+ "duplicateKeys": {
48
+ "enum": [
49
+ "first",
50
+ "last",
51
+ "error"
52
+ ]
139
53
  },
140
- "flags": {
141
- "type": "object",
142
- "additionalProperties": {
143
- "$ref": "#/$defs/flag"
144
- },
145
- "description": "Named flag definitions keyed by flag name."
54
+ "elementSchema": {
55
+ "$ref": "#/$defs/argElement",
56
+ "description": "Element schema when `kind === 'keyValue'`.\n\nDescribes the value of each entry, so `arg.keyValue(arg.number())` decodes\n`A=1` to the number `1`. `undefined` leaves entry values as strings."
146
57
  },
147
- "args": {
58
+ "enumValues": {
59
+ "description": "Allowed literal values when `kind === 'enum'`.",
148
60
  "type": "array",
149
61
  "items": {
150
- "$ref": "#/$defs/arg"
151
- },
152
- "description": "Positional argument definitions in CLI order."
62
+ "type": "string"
63
+ }
64
+ },
65
+ "envVar": {
66
+ "description": "Environment variable name for env resolution.\n\nWhen set and the CLI value is absent, the resolver reads this env var\nand coerces the string to the arg's declared kind.",
67
+ "type": "string"
153
68
  },
154
- "commands": {
155
- "type": "array",
156
- "items": {
157
- "$ref": "#/$defs/command"
158
- },
159
- "description": "Nested subcommand definitions."
160
- }
161
- },
162
- "required": [
163
- "schemaVersion",
164
- "name",
165
- "flags",
166
- "args",
167
- "commands"
168
- ],
169
- "description": "A single-command definition document, version 1.\n\nProduced by generateCommandSchema. Same shape as a\nCommandDefinitionFragmentV1 plus the `schemaVersion` every standalone\ndocument carries."
170
- },
171
- "flag": {
172
- "type": "object",
173
- "additionalProperties": false,
174
- "properties": {
175
69
  "kind": {
70
+ "description": "What kind of value this arg accepts.",
176
71
  "enum": [
177
72
  "string",
178
73
  "number",
179
74
  "boolean",
180
75
  "enum",
181
- "array",
182
76
  "custom",
183
- "count",
184
77
  "keyValue"
185
- ],
186
- "description": "What kind of value this flag accepts."
78
+ ]
79
+ },
80
+ "name": {
81
+ "description": "A named positional argument entry in the command schema.\n\nPairs a user-facing arg name with its ArgSchema descriptor.\nThe array ordering in CommandSchema.args determines CLI position.",
82
+ "type": "string"
83
+ },
84
+ "numberConstraints": {
85
+ "$ref": "#/$defs/numberConstraints"
86
+ },
87
+ "pathChecks": {
88
+ "$ref": "#/$defs/pathChecks"
187
89
  },
188
90
  "presence": {
91
+ "description": "Presence describes whether a positional arg is guaranteed to exist when the\naction handler runs:\n\n- `'required'` — must be supplied; error if missing (default)\n- `'optional'` — may be `undefined` if not supplied\n- `'defaulted'` — always present (falls back to default value)",
189
92
  "enum": [
190
- "optional",
191
93
  "required",
94
+ "optional",
192
95
  "defaulted"
193
- ],
194
- "description": "Presence describes whether a flag value is guaranteed to exist when the\naction handler runs:\n\n- `'optional'` — not required; unresolved value follows the kind-specific\n optional fallback (`undefined` for most flags, `[]` for arrays)\n- `'required'` — must be supplied; error if missing\n- `'defaulted'` — always present (falls back to default value)"
195
- },
196
- "defaultValue": {
197
- "description": "Runtime default value (if any)."
198
- },
199
- "aliases": {
200
- "type": "array",
201
- "items": {
202
- "type": "string"
203
- },
204
- "description": "Short/long aliases (e.g. `[{ name: 'f', hidden: false }]` for `--force`)."
205
- },
206
- "stdin": {
207
- "$ref": "#/$defs/stdin",
208
- "description": "Stdin binding set by `.stdin()` (`undefined` when the flag never reads\nstdin). See StdinBinding."
209
- },
210
- "envVar": {
211
- "type": "string",
212
- "description": "Environment variable name for v0.2+ resolution."
213
- },
214
- "configPath": {
215
- "type": "string",
216
- "description": "Dotted config path for v0.2+ resolution (e.g. `'deploy.region'`)."
217
- },
218
- "description": {
219
- "type": "string",
220
- "description": "Human-readable description for help text."
221
- },
222
- "enumValues": {
223
- "type": "array",
224
- "items": {
225
- "type": "string"
226
- },
227
- "description": "Allowed literal values when `kind === 'enum'`."
228
- },
229
- "numberConstraints": {
230
- "$ref": "#/$defs/numberConstraints"
96
+ ]
231
97
  },
232
- "stringConstraints": {
233
- "$ref": "#/$defs/stringConstraints"
98
+ "prompt": {
99
+ "$ref": "#/$defs/prompt",
100
+ "description": "Interactive prompt configuration."
234
101
  },
235
- "elementSchema": {
236
- "$ref": "#/$defs/flag",
237
- "description": "Element schema when `kind === 'array'` or `kind === 'keyValue'`."
102
+ "sensitive": {
103
+ "description": "Whether values from this input must be kept out of user-facing projections.",
104
+ "const": true
238
105
  },
239
106
  "separator": {
240
107
  "type": "string",
@@ -243,355 +110,503 @@
243
110
  "split": {
244
111
  "$ref": "#/$defs/split"
245
112
  },
246
- "duplicateKeys": {
247
- "enum": [
248
- "first",
249
- "last",
250
- "error"
251
- ]
113
+ "stdin": {
114
+ "$ref": "#/$defs/stdin",
115
+ "description": "Stdin binding set by `.stdin()` (`undefined` when the arg never reads\nstdin). See StdinBinding."
116
+ },
117
+ "stringConstraints": {
118
+ "$ref": "#/$defs/stringConstraints"
252
119
  },
253
120
  "unique": {
254
121
  "const": true
255
122
  },
256
- "pathChecks": {
257
- "$ref": "#/$defs/pathChecks"
258
- },
259
123
  "valueHint": {
260
124
  "type": "string"
261
125
  },
262
- "prompt": {
263
- "$ref": "#/$defs/prompt",
264
- "description": "Interactive prompt configuration for v0.3+ resolution."
126
+ "variadic": {
127
+ "description": "Whether this arg consumes all remaining positionals.",
128
+ "const": true
129
+ }
130
+ },
131
+ "additionalProperties": false,
132
+ "anyOf": [
133
+ {
134
+ "not": {
135
+ "required": [
136
+ "elementSchema"
137
+ ]
138
+ }
265
139
  },
266
- "deprecated": {
267
- "oneOf": [
268
- {
269
- "type": "string"
270
- },
271
- {
272
- "const": true
273
- }
274
- ],
275
- "description": "Deprecation marker.\n\n- `undefined` — not deprecated (default)\n- `true` — deprecated with no migration message\n- `string` — deprecated with a reason/migration message\n\nWhen a deprecated flag is used, a warning is emitted to stderr.\nHelp text shows `[deprecated]` or `[deprecated: <reason>]`."
276
- },
277
- "propagate": {
278
- "const": true,
279
- "description": "Whether this flag propagates to subcommands in nested command trees.\n\nWhen `true`, the flag is automatically available to all descendant\ncommands. A child command that defines a flag with the same name\nshadows the propagated parent flag.\n\nDefault: `false`"
280
- },
281
- "negation": {
282
- "$ref": "#/$defs/negation",
283
- "description": "Negation settings when `kind === 'boolean'` and `.negatable()` was\ncalled (`undefined` otherwise). See FlagNegation."
284
- },
285
- "duplicates": {
286
- "enum": [
287
- "last",
288
- "first",
289
- "error"
140
+ {
141
+ "required": [
142
+ "kind"
290
143
  ],
291
- "description": "How repeated CLI occurrences of a singleton flag combine.\n\n- `'last'` — last occurrence wins (matches historic behavior)\n- `'first'` — first occurrence wins; later ones parse but are ignored\n- `'error'` — a second occurrence is a `ParseError` (`DUPLICATE_FLAG`)\n\nApplies to CLI token occurrences only — env/config/prompt/default\nresolution keeps its precedence semantics and never raises duplicates.\nOccurrences are counted per *logical* flag: aliases and the negated\nspelling all count toward the same flag.\n\nDefault: `'last'`"
144
+ "properties": {
145
+ "kind": {
146
+ "const": "keyValue"
147
+ }
148
+ }
292
149
  }
293
- },
150
+ ]
151
+ },
152
+ "argElement": {
153
+ "description": "Element schema when `kind === 'keyValue'`.\n\nDescribes the value of each entry, so `arg.keyValue(arg.number())` decodes\n`A=1` to the number `1`. `undefined` leaves entry values as strings.",
154
+ "type": "object",
294
155
  "required": [
295
156
  "kind",
296
157
  "presence"
297
158
  ],
298
- "description": "The runtime descriptor stored inside every FlagBuilder. Consumers (parser,\nhelp generator, resolution chain) read this to understand the flag's shape\nwithout touching generics."
299
- },
300
- "stdin": {
301
- "type": "object",
302
- "additionalProperties": false,
303
159
  "properties": {
304
- "when": {
305
- "enum": [
306
- "dash",
307
- "missing",
308
- "dash-or-missing"
309
- ],
310
- "description": "When this input reads the stdin stream."
160
+ "enumValues": {
161
+ "description": "Allowed literal values when `kind === 'enum'`.",
162
+ "type": "array",
163
+ "items": {
164
+ "type": "string"
165
+ }
311
166
  },
312
- "consume": {
167
+ "kind": {
168
+ "description": "What kind of value this arg accepts.",
313
169
  "enum": [
314
- "exclusive",
315
- "broadcast"
316
- ],
317
- "description": "Whether this input consumes the stream alone."
170
+ "string",
171
+ "number",
172
+ "boolean",
173
+ "enum",
174
+ "custom"
175
+ ]
318
176
  },
319
- "trim": {
320
- "type": "boolean",
321
- "description": "Whether one trailing line terminator is dropped from a single value."
177
+ "numberConstraints": {
178
+ "$ref": "#/$defs/numberConstraints"
179
+ },
180
+ "pathChecks": {
181
+ "$ref": "#/$defs/pathChecks"
182
+ },
183
+ "presence": {
184
+ "description": "Entry values are required once their containing key-value argument is present.",
185
+ "const": "required"
186
+ },
187
+ "stringConstraints": {
188
+ "$ref": "#/$defs/stringConstraints"
189
+ },
190
+ "valueHint": {
191
+ "type": "string"
322
192
  }
323
193
  },
324
- "required": [
325
- "when",
326
- "consume"
327
- ],
328
- "description": "The normalized stdin axis of a flag or an arg."
194
+ "additionalProperties": false
329
195
  },
330
- "split": {
196
+ "choice": {
197
+ "description": "A selectable option for SelectPromptConfig and MultiselectPromptConfig prompts.",
331
198
  "type": "object",
332
- "additionalProperties": false,
199
+ "required": [
200
+ "value"
201
+ ],
333
202
  "properties": {
334
- "env": {
335
- "$ref": "#/$defs/splitPolicy"
203
+ "description": {
204
+ "description": "Optional description shown alongside the choice.",
205
+ "type": "string"
336
206
  },
337
- "stdin": {
338
- "$ref": "#/$defs/splitPolicy"
339
- }
340
- }
341
- },
342
- "splitPolicy": {
343
- "type": "object",
344
- "additionalProperties": false,
345
- "properties": {
346
- "format": {
347
- "enum": [
348
- "whole",
349
- "delimiter",
350
- "lines",
351
- "json"
352
- ]
207
+ "label": {
208
+ "description": "Display label shown to the user.\n\nDefault: value",
209
+ "type": "string"
353
210
  },
354
- "delimiter": {
355
- "type": "string",
356
- "minLength": 1
211
+ "value": {
212
+ "description": "The value returned when this choice is selected.",
213
+ "type": "string"
357
214
  }
358
215
  },
216
+ "additionalProperties": false
217
+ },
218
+ "command": {
219
+ "description": "Runtime descriptor produced by CommandBuilder.\n\nConsumers (parser, help generator, CLI dispatcher) read this to\nunderstand the command's shape — flags, args, aliases, subcommands,\nand interactive resolver.",
220
+ "type": "object",
359
221
  "required": [
360
- "format"
222
+ "args",
223
+ "commands",
224
+ "flags",
225
+ "name"
361
226
  ],
362
- "oneOf": [
363
- {
364
- "properties": {
365
- "format": {
366
- "const": "delimiter"
367
- }
368
- },
369
- "required": [
370
- "format",
371
- "delimiter"
372
- ]
227
+ "properties": {
228
+ "aliases": {
229
+ "description": "Alternative names for this command.",
230
+ "type": "array",
231
+ "items": {
232
+ "type": "string"
233
+ }
373
234
  },
374
- {
375
- "properties": {
376
- "format": {
377
- "enum": [
378
- "whole",
379
- "lines",
380
- "json"
381
- ]
382
- }
383
- },
384
- "not": {
385
- "required": [
386
- "delimiter"
387
- ]
235
+ "args": {
236
+ "description": "Ordered positional arg entries (name + schema).",
237
+ "type": "array",
238
+ "items": {
239
+ "$ref": "#/$defs/arg"
240
+ }
241
+ },
242
+ "commands": {
243
+ "description": "Nested subcommand schemas (for help rendering and completion).\n\nPure data — no execution closures. Populated by `.command()` on\n`CommandBuilder`. Empty for leaf commands.",
244
+ "type": "array",
245
+ "items": {
246
+ "$ref": "#/$defs/command"
247
+ }
248
+ },
249
+ "description": {
250
+ "description": "Human-readable description for help text.",
251
+ "type": "string"
252
+ },
253
+ "examples": {
254
+ "description": "Usage examples for help text.",
255
+ "type": "array",
256
+ "items": {
257
+ "$ref": "#/$defs/example"
388
258
  }
259
+ },
260
+ "flags": {
261
+ "description": "Named flag schemas, keyed by flag name.",
262
+ "type": "object",
263
+ "additionalProperties": {
264
+ "$ref": "#/$defs/flag"
265
+ }
266
+ },
267
+ "hidden": {
268
+ "description": "Whether this command is hidden from help listings.",
269
+ "const": true
270
+ },
271
+ "name": {
272
+ "description": "The command name (used for dispatch, e.g. `'deploy'`).",
273
+ "type": "string"
389
274
  }
390
- ]
275
+ },
276
+ "additionalProperties": false
391
277
  },
392
- "negation": {
278
+ "commandDocument": {
279
+ "description": "A single-command definition document, version 1.\n\nProduced by generateCommandSchema. Same shape as a\nCommandDefinitionFragmentV1 plus the `schemaVersion` every standalone\ndocument carries.",
393
280
  "type": "object",
394
- "additionalProperties": false,
281
+ "required": [
282
+ "args",
283
+ "commands",
284
+ "flags",
285
+ "name",
286
+ "schemaVersion"
287
+ ],
395
288
  "properties": {
396
- "alias": {
397
- "type": "string",
398
- "description": "Explicit negated spelling without the `--` prefix (e.g. `'no-sandbox'`).\n`undefined` synthesizes `no-<flagName>` wherever the flag name is known."
289
+ "aliases": {
290
+ "description": "Alternative names accepted for this command.",
291
+ "type": "array",
292
+ "items": {
293
+ "type": "string"
294
+ }
295
+ },
296
+ "args": {
297
+ "description": "Positional argument definitions in CLI order.",
298
+ "type": "array",
299
+ "items": {
300
+ "$ref": "#/$defs/arg"
301
+ }
302
+ },
303
+ "commands": {
304
+ "description": "Nested subcommand definitions.",
305
+ "type": "array",
306
+ "items": {
307
+ "$ref": "#/$defs/command"
308
+ }
309
+ },
310
+ "description": {
311
+ "description": "Human-readable description for help text.",
312
+ "type": "string"
313
+ },
314
+ "examples": {
315
+ "description": "Usage examples attached to the command.",
316
+ "type": "array",
317
+ "items": {
318
+ "$ref": "#/$defs/example"
319
+ }
320
+ },
321
+ "flags": {
322
+ "description": "Named flag definitions keyed by flag name.",
323
+ "type": "object",
324
+ "additionalProperties": {
325
+ "$ref": "#/$defs/flag"
326
+ }
399
327
  },
400
328
  "hidden": {
401
- "const": true,
402
- "description": "Hide the negated spelling from help, completions, and suggestions."
329
+ "description": "Whether the command is omitted from help listings.",
330
+ "const": true
331
+ },
332
+ "name": {
333
+ "description": "The command name used for dispatch.",
334
+ "type": "string"
335
+ },
336
+ "schemaVersion": {
337
+ "description": "Version of the definition document format emitted by `generateSchema()`\nand `generateCommandSchema()` from `@kjanat/dreamcli/json-schema`.",
338
+ "const": 1
403
339
  }
404
340
  },
405
- "description": "Negation settings for a boolean flag (set by `.negatable()`).\n\nThe negated spelling and the positive form are two spellings of ONE\nlogical flag: they share duplicate policy, and the last CLI occurrence\nwins across both. The negated spelling is presence-only — `--no-foo=x`\nis rejected."
341
+ "additionalProperties": false
406
342
  },
407
- "numberConstraints": {
343
+ "example": {
344
+ "description": "A single usage example shown in help text.",
408
345
  "type": "object",
409
- "additionalProperties": false,
346
+ "required": [
347
+ "command"
348
+ ],
410
349
  "properties": {
411
- "min": {
412
- "type": "number"
413
- },
414
- "max": {
415
- "type": "number"
416
- },
417
- "int": {
418
- "type": "boolean"
350
+ "command": {
351
+ "description": "The command invocation (e.g. `'deploy production --force'`).",
352
+ "type": "string"
419
353
  },
420
- "finite": {
421
- "type": "boolean"
354
+ "description": {
355
+ "description": "Optional description of what this example does.",
356
+ "type": "string"
422
357
  }
423
- }
358
+ },
359
+ "additionalProperties": false
424
360
  },
425
- "stringConstraints": {
361
+ "flag": {
362
+ "description": "The runtime descriptor stored inside every FlagBuilder. Consumers (parser,\nhelp generator, resolution chain) read this to understand the flag's shape\nwithout touching generics.",
426
363
  "type": "object",
427
- "additionalProperties": false,
364
+ "required": [
365
+ "kind",
366
+ "presence"
367
+ ],
428
368
  "properties": {
429
- "nonEmpty": {
430
- "type": "boolean"
431
- },
432
- "minLength": {
433
- "type": "integer",
434
- "minimum": 0
369
+ "aliases": {
370
+ "description": "Short/long aliases (e.g. `[{ name: 'f', hidden: false }]` for `--force`).",
371
+ "type": "array",
372
+ "items": {
373
+ "type": "string"
374
+ }
435
375
  },
436
- "maxLength": {
437
- "type": "integer",
438
- "minimum": 0
376
+ "configPath": {
377
+ "description": "Dotted config path for v0.2+ resolution (e.g. `'deploy.region'`).",
378
+ "type": "string"
439
379
  },
440
- "pattern": {
441
- "type": "object",
442
- "additionalProperties": false,
443
- "properties": {
444
- "source": {
380
+ "defaultDescription": {
381
+ "description": "Human-readable replacement for the default value in help, or `false` to\nomit the default annotation.",
382
+ "oneOf": [
383
+ {
445
384
  "type": "string"
446
385
  },
447
- "flags": {
386
+ {
387
+ "const": false
388
+ }
389
+ ]
390
+ },
391
+ "defaultValue": {
392
+ "description": "Runtime default value (if any)."
393
+ },
394
+ "deprecated": {
395
+ "description": "Deprecation marker.\n\n- `undefined` — not deprecated (default)\n- `true` — deprecated with no migration message\n- `string` — deprecated with a reason/migration message\n\nWhen a deprecated flag is used, a warning is emitted to stderr.\nHelp text shows `[deprecated]` or `[deprecated: <reason>]`.",
396
+ "oneOf": [
397
+ {
448
398
  "type": "string"
399
+ },
400
+ {
401
+ "const": true
449
402
  }
450
- },
451
- "required": [
452
- "source",
453
- "flags"
454
403
  ]
455
- }
456
- }
457
- },
458
- "pathChecks": {
459
- "type": "object",
460
- "additionalProperties": false,
461
- "properties": {
462
- "mustExist": {
463
- "type": "boolean"
464
404
  },
465
- "type": {
405
+ "description": {
406
+ "description": "Human-readable description for help text.",
407
+ "type": "string"
408
+ },
409
+ "duplicateKeys": {
466
410
  "enum": [
467
- "file",
468
- "directory"
411
+ "first",
412
+ "last",
413
+ "error"
469
414
  ]
470
415
  },
471
- "create": {
472
- "const": true
473
- }
474
- },
475
- "required": [
476
- "mustExist"
477
- ]
478
- },
479
- "argElement": {
480
- "type": "object",
481
- "additionalProperties": false,
482
- "properties": {
483
- "kind": {
416
+ "duplicates": {
417
+ "description": "How repeated CLI occurrences of a singleton flag combine.\n\n- `'last'` — last occurrence wins (matches historic behavior)\n- `'first'` — first occurrence wins; later ones parse but are ignored\n- `'error'` — a second occurrence is a `ParseError` (`DUPLICATE_FLAG`)\n\nApplies to CLI token occurrences only — env/config/prompt/default\nresolution keeps its precedence semantics and never raises duplicates.\nOccurrences are counted per *logical* flag: aliases and the negated\nspelling all count toward the same flag.\n\nDefault: `'last'`",
484
418
  "enum": [
485
- "string",
486
- "number",
487
- "boolean",
488
- "enum",
489
- "custom"
490
- ],
491
- "description": "What kind of value this arg accepts."
419
+ "last",
420
+ "first",
421
+ "error"
422
+ ]
492
423
  },
493
- "presence": {
494
- "const": "required",
495
- "description": "Entry values are required once their containing key-value argument is present."
424
+ "elementSchema": {
425
+ "$ref": "#/$defs/flagElement",
426
+ "description": "Element schema when `kind === 'array'` or `kind === 'keyValue'`."
496
427
  },
497
428
  "enumValues": {
429
+ "description": "Allowed literal values when `kind === 'enum'`.",
498
430
  "type": "array",
499
431
  "items": {
500
432
  "type": "string"
501
- },
502
- "description": "Allowed literal values when `kind === 'enum'`."
503
- },
504
- "numberConstraints": {
505
- "$ref": "#/$defs/numberConstraints"
506
- },
507
- "stringConstraints": {
508
- "$ref": "#/$defs/stringConstraints"
509
- },
510
- "pathChecks": {
511
- "$ref": "#/$defs/pathChecks"
433
+ }
512
434
  },
513
- "valueHint": {
435
+ "envVar": {
436
+ "description": "Environment variable name for v0.2+ resolution.",
514
437
  "type": "string"
515
- }
516
- },
517
- "required": [
518
- "kind",
519
- "presence"
520
- ],
521
- "description": "Element schema when `kind === 'keyValue'`.\n\nDescribes the value of each entry, so `arg.keyValue(arg.number())` decodes\n`A=1` to the number `1`. `undefined` leaves entry values as strings."
522
- },
523
- "arg": {
524
- "type": "object",
525
- "additionalProperties": false,
526
- "properties": {
527
- "name": {
528
- "type": "string",
529
- "description": "A named positional argument entry in the command schema.\n\nPairs a user-facing arg name with its ArgSchema descriptor.\nThe array ordering in CommandSchema.args determines CLI position."
530
438
  },
531
439
  "kind": {
440
+ "description": "What kind of value this flag accepts.",
532
441
  "enum": [
533
442
  "string",
534
443
  "number",
535
444
  "boolean",
536
445
  "enum",
446
+ "array",
537
447
  "custom",
448
+ "count",
538
449
  "keyValue"
539
- ],
540
- "description": "What kind of value this arg accepts."
450
+ ]
451
+ },
452
+ "negation": {
453
+ "$ref": "#/$defs/negation",
454
+ "description": "Negation settings when `kind === 'boolean'` and `.negatable()` was\ncalled (`undefined` otherwise). See FlagNegation."
455
+ },
456
+ "numberConstraints": {
457
+ "$ref": "#/$defs/numberConstraints"
458
+ },
459
+ "pathChecks": {
460
+ "$ref": "#/$defs/pathChecks"
541
461
  },
542
462
  "presence": {
463
+ "description": "Presence describes whether a flag value is guaranteed to exist when the\naction handler runs:\n\n- `'optional'` — not required; unresolved value follows the kind-specific\n optional fallback (`undefined` for most flags, `[]` for arrays)\n- `'required'` — must be supplied; error if missing\n- `'defaulted'` — always present (falls back to default value)",
543
464
  "enum": [
544
- "required",
545
465
  "optional",
466
+ "required",
546
467
  "defaulted"
547
- ],
548
- "description": "Presence describes whether a positional arg is guaranteed to exist when the\naction handler runs:\n\n- `'required'` — must be supplied; error if missing (default)\n- `'optional'` — may be `undefined` if not supplied\n- `'defaulted'` — always present (falls back to default value)"
468
+ ]
549
469
  },
550
- "variadic": {
551
- "const": true,
552
- "description": "Whether this arg consumes all remaining positionals."
470
+ "prompt": {
471
+ "$ref": "#/$defs/prompt",
472
+ "description": "Interactive prompt configuration for v0.3+ resolution."
473
+ },
474
+ "propagate": {
475
+ "description": "Whether this flag propagates to subcommands in nested command trees.\n\nWhen `true`, the flag is automatically available to all descendant\ncommands. A child command that defines a flag with the same name\nshadows the propagated parent flag.\n\nDefault: `false`",
476
+ "const": true
477
+ },
478
+ "sensitive": {
479
+ "description": "Whether values from this input must be kept out of user-facing projections.",
480
+ "const": true
481
+ },
482
+ "separator": {
483
+ "type": "string",
484
+ "minLength": 1
485
+ },
486
+ "split": {
487
+ "$ref": "#/$defs/split"
553
488
  },
554
489
  "stdin": {
555
490
  "$ref": "#/$defs/stdin",
556
- "description": "Stdin binding set by `.stdin()` (`undefined` when the arg never reads\nstdin). See StdinBinding."
491
+ "description": "Stdin binding set by `.stdin()` (`undefined` when the flag never reads\nstdin). See StdinBinding."
492
+ },
493
+ "stringConstraints": {
494
+ "$ref": "#/$defs/stringConstraints"
495
+ },
496
+ "unique": {
497
+ "const": true
498
+ },
499
+ "valueHint": {
500
+ "type": "string"
501
+ }
502
+ },
503
+ "additionalProperties": false
504
+ },
505
+ "flagElement": {
506
+ "description": "Element schema when `kind === 'array'` or `kind === 'keyValue'`.",
507
+ "type": "object",
508
+ "required": [
509
+ "kind",
510
+ "presence"
511
+ ],
512
+ "properties": {
513
+ "aliases": {
514
+ "description": "Short/long aliases (e.g. `[{ name: 'f', hidden: false }]` for `--force`).",
515
+ "type": "array",
516
+ "items": {
517
+ "type": "string"
518
+ }
519
+ },
520
+ "configPath": {
521
+ "description": "Dotted config path for v0.2+ resolution (e.g. `'deploy.region'`).",
522
+ "type": "string"
557
523
  },
558
524
  "defaultValue": {
559
525
  "description": "Runtime default value (if any)."
560
526
  },
527
+ "deprecated": {
528
+ "description": "Deprecation marker.\n\n- `undefined` — not deprecated (default)\n- `true` — deprecated with no migration message\n- `string` — deprecated with a reason/migration message\n\nWhen a deprecated flag is used, a warning is emitted to stderr.\nHelp text shows `[deprecated]` or `[deprecated: <reason>]`.",
529
+ "oneOf": [
530
+ {
531
+ "type": "string"
532
+ },
533
+ {
534
+ "const": true
535
+ }
536
+ ]
537
+ },
561
538
  "description": {
562
- "type": "string",
563
- "description": "Human-readable description for help text."
539
+ "description": "Human-readable description for help text.",
540
+ "type": "string"
564
541
  },
565
- "envVar": {
566
- "type": "string",
567
- "description": "Environment variable name for env resolution.\n\nWhen set and the CLI value is absent, the resolver reads this env var\nand coerces the string to the arg's declared kind."
542
+ "duplicateKeys": {
543
+ "enum": [
544
+ "first",
545
+ "last",
546
+ "error"
547
+ ]
568
548
  },
569
- "configPath": {
570
- "type": "string",
571
- "description": "Dotted config path for config resolution (e.g. `'deploy.region'`)."
549
+ "duplicates": {
550
+ "description": "How repeated CLI occurrences of a singleton flag combine.\n\n- `'last'` — last occurrence wins (matches historic behavior)\n- `'first'` — first occurrence wins; later ones parse but are ignored\n- `'error'` — a second occurrence is a `ParseError` (`DUPLICATE_FLAG`)\n\nApplies to CLI token occurrences only — env/config/prompt/default\nresolution keeps its precedence semantics and never raises duplicates.\nOccurrences are counted per *logical* flag: aliases and the negated\nspelling all count toward the same flag.\n\nDefault: `'last'`",
551
+ "enum": [
552
+ "last",
553
+ "first",
554
+ "error"
555
+ ]
556
+ },
557
+ "elementSchema": {
558
+ "$ref": "#/$defs/flagElement",
559
+ "description": "Element schema when `kind === 'array'` or `kind === 'keyValue'`."
572
560
  },
573
561
  "enumValues": {
562
+ "description": "Allowed literal values when `kind === 'enum'`.",
574
563
  "type": "array",
575
564
  "items": {
576
565
  "type": "string"
577
- },
578
- "description": "Allowed literal values when `kind === 'enum'`."
566
+ }
579
567
  },
580
- "elementSchema": {
581
- "$ref": "#/$defs/argElement",
582
- "description": "Element schema when `kind === 'keyValue'`.\n\nDescribes the value of each entry, so `arg.keyValue(arg.number())` decodes\n`A=1` to the number `1`. `undefined` leaves entry values as strings."
568
+ "envVar": {
569
+ "description": "Environment variable name for v0.2+ resolution.",
570
+ "type": "string"
571
+ },
572
+ "kind": {
573
+ "description": "What kind of value this flag accepts.",
574
+ "enum": [
575
+ "string",
576
+ "number",
577
+ "boolean",
578
+ "enum",
579
+ "array",
580
+ "custom",
581
+ "count",
582
+ "keyValue"
583
+ ]
584
+ },
585
+ "negation": {
586
+ "$ref": "#/$defs/negation",
587
+ "description": "Negation settings when `kind === 'boolean'` and `.negatable()` was\ncalled (`undefined` otherwise). See FlagNegation."
583
588
  },
584
589
  "numberConstraints": {
585
590
  "$ref": "#/$defs/numberConstraints"
586
591
  },
587
- "stringConstraints": {
588
- "$ref": "#/$defs/stringConstraints"
589
- },
590
592
  "pathChecks": {
591
593
  "$ref": "#/$defs/pathChecks"
592
594
  },
593
- "valueHint": {
594
- "type": "string"
595
+ "presence": {
596
+ "description": "Presence describes whether a flag value is guaranteed to exist when the\naction handler runs:\n\n- `'optional'` — not required; unresolved value follows the kind-specific\n optional fallback (`undefined` for most flags, `[]` for arrays)\n- `'required'` — must be supplied; error if missing\n- `'defaulted'` — always present (falls back to default value)",
597
+ "enum": [
598
+ "optional",
599
+ "required",
600
+ "defaulted"
601
+ ]
602
+ },
603
+ "prompt": {
604
+ "$ref": "#/$defs/prompt",
605
+ "description": "Interactive prompt configuration for v0.3+ resolution."
606
+ },
607
+ "propagate": {
608
+ "description": "Whether this flag propagates to subcommands in nested command trees.\n\nWhen `true`, the flag is automatically available to all descendant\ncommands. A child command that defines a flag with the same name\nshadows the propagated parent flag.\n\nDefault: `false`",
609
+ "const": true
595
610
  },
596
611
  "separator": {
597
612
  "type": "string",
@@ -600,140 +615,284 @@
600
615
  "split": {
601
616
  "$ref": "#/$defs/split"
602
617
  },
603
- "duplicateKeys": {
604
- "enum": [
605
- "first",
606
- "last",
607
- "error"
608
- ]
618
+ "stdin": {
619
+ "$ref": "#/$defs/stdin",
620
+ "description": "Stdin binding set by `.stdin()` (`undefined` when the flag never reads\nstdin). See StdinBinding."
621
+ },
622
+ "stringConstraints": {
623
+ "$ref": "#/$defs/stringConstraints"
609
624
  },
610
625
  "unique": {
611
626
  "const": true
612
627
  },
613
- "prompt": {
614
- "$ref": "#/$defs/prompt",
615
- "description": "Interactive prompt configuration."
628
+ "valueHint": {
629
+ "type": "string"
630
+ }
631
+ },
632
+ "additionalProperties": false
633
+ },
634
+ "negation": {
635
+ "description": "Negation settings for a boolean flag (set by `.negatable()`).\n\nThe negated spelling and the positive form are two spellings of ONE\nlogical flag: they share duplicate policy, and the last CLI occurrence\nwins across both. The negated spelling is presence-only — `--no-foo=x`\nis rejected.",
636
+ "type": "object",
637
+ "properties": {
638
+ "alias": {
639
+ "description": "Explicit negated spelling without the `--` prefix (e.g. `'no-sandbox'`).\n`undefined` synthesizes `no-<flagName>` wherever the flag name is known.",
640
+ "type": "string"
616
641
  },
617
- "deprecated": {
618
- "oneOf": [
619
- {
620
- "type": "string"
621
- },
622
- {
623
- "const": true
624
- }
625
- ],
626
- "description": "Deprecation marker.\n\n- `undefined` — not deprecated (default)\n- `true` — deprecated with no migration message\n- `string` — deprecated with a reason/migration message\n\nWhen a deprecated arg is used, a warning is emitted to stderr.\nHelp text shows `[deprecated]` or `[deprecated: <reason>]`."
642
+ "hidden": {
643
+ "description": "Hide the negated spelling from help, completions, and suggestions.",
644
+ "const": true
645
+ }
646
+ },
647
+ "additionalProperties": false
648
+ },
649
+ "numberConstraints": {
650
+ "type": "object",
651
+ "properties": {
652
+ "finite": {
653
+ "type": "boolean"
654
+ },
655
+ "int": {
656
+ "type": "boolean"
657
+ },
658
+ "max": {
659
+ "type": "number"
660
+ },
661
+ "min": {
662
+ "type": "number"
627
663
  }
628
664
  },
665
+ "additionalProperties": false
666
+ },
667
+ "pathChecks": {
668
+ "type": "object",
629
669
  "required": [
630
- "name",
631
- "kind",
632
- "presence"
670
+ "mustExist"
633
671
  ],
634
- "anyOf": [
635
- {
636
- "not": {
637
- "required": [
638
- "elementSchema"
639
- ]
640
- }
672
+ "properties": {
673
+ "create": {
674
+ "const": true
641
675
  },
642
- {
643
- "properties": {
644
- "kind": {
645
- "const": "keyValue"
646
- }
647
- },
648
- "required": [
649
- "kind"
676
+ "mustExist": {
677
+ "type": "boolean"
678
+ },
679
+ "type": {
680
+ "enum": [
681
+ "file",
682
+ "directory"
650
683
  ]
651
684
  }
652
- ],
653
- "description": "The runtime descriptor stored inside every ArgBuilder. Consumers (parser,\nhelp generator) read this to understand the arg's shape without touching\ngenerics."
685
+ },
686
+ "additionalProperties": false
654
687
  },
655
688
  "prompt": {
689
+ "description": "Discriminated union of all prompt configurations.\n\nUse the `kind` field to narrow:\n```ts\nif (config.kind === 'select') {\n config.choices // readonly SelectChoice[] | undefined\n}\n```",
656
690
  "type": "object",
657
- "additionalProperties": false,
691
+ "required": [
692
+ "kind",
693
+ "message"
694
+ ],
658
695
  "properties": {
696
+ "choices": {
697
+ "description": "Available choices. When omitted for `enum` flags, the enum values\nfrom the flag schema are used automatically.",
698
+ "type": "array",
699
+ "items": {
700
+ "$ref": "#/$defs/choice"
701
+ }
702
+ },
659
703
  "kind": {
704
+ "description": "The kind of interactive prompt to present.\n\n- `'confirm'` — yes/no boolean question\n- `'input'` — free-text string input\n- `'select'` — single selection from a list\n- `'multiselect'` — multiple selections from a list",
660
705
  "enum": [
661
706
  "confirm",
662
707
  "input",
663
708
  "select",
664
709
  "multiselect"
665
- ],
666
- "description": "The kind of interactive prompt to present.\n\n- `'confirm'` — yes/no boolean question\n- `'input'` — free-text string input\n- `'select'` — single selection from a list\n- `'multiselect'` — multiple selections from a list"
667
- },
668
- "message": {
669
- "type": "string",
670
- "description": "The question displayed to the user."
710
+ ]
671
711
  },
672
- "placeholder": {
673
- "type": "string",
674
- "description": "Placeholder text shown before user types (informational only)."
712
+ "max": {
713
+ "description": "Maximum number of selections allowed.\n\nDefault: `Infinity`",
714
+ "type": "integer"
675
715
  },
676
- "choices": {
677
- "type": "array",
678
- "items": {
679
- "$ref": "#/$defs/choice"
680
- },
681
- "description": "Available choices. When omitted for `enum` flags, the enum values\nfrom the flag schema are used automatically."
716
+ "message": {
717
+ "description": "The question displayed to the user.",
718
+ "type": "string"
682
719
  },
683
720
  "min": {
684
- "type": "integer",
685
- "description": "Minimum number of selections required.\n\nDefault: `0`"
721
+ "description": "Minimum number of selections required.\n\nDefault: `0`",
722
+ "type": "integer"
686
723
  },
687
- "max": {
688
- "type": "integer",
689
- "description": "Maximum number of selections allowed.\n\nDefault: `Infinity`"
724
+ "placeholder": {
725
+ "description": "Placeholder text shown before user types (informational only).",
726
+ "type": "string"
690
727
  }
691
728
  },
692
- "required": [
693
- "kind",
694
- "message"
695
- ],
696
- "description": "Discriminated union of all prompt configurations.\n\nUse the `kind` field to narrow:\n```ts\nif (config.kind === 'select') {\n config.choices // readonly SelectChoice[] | undefined\n}\n```"
729
+ "additionalProperties": false
697
730
  },
698
- "choice": {
731
+ "split": {
699
732
  "type": "object",
700
- "additionalProperties": false,
701
733
  "properties": {
702
- "value": {
703
- "type": "string",
704
- "description": "The value returned when this choice is selected."
734
+ "env": {
735
+ "$ref": "#/$defs/splitPolicy"
705
736
  },
706
- "label": {
737
+ "stdin": {
738
+ "$ref": "#/$defs/splitPolicy"
739
+ }
740
+ },
741
+ "additionalProperties": false
742
+ },
743
+ "splitPolicy": {
744
+ "type": "object",
745
+ "required": [
746
+ "format"
747
+ ],
748
+ "properties": {
749
+ "delimiter": {
707
750
  "type": "string",
708
- "description": "Display label shown to the user.\n\nDefault: value"
751
+ "minLength": 1
709
752
  },
710
- "description": {
711
- "type": "string",
712
- "description": "Optional description shown alongside the choice."
753
+ "format": {
754
+ "enum": [
755
+ "whole",
756
+ "delimiter",
757
+ "lines",
758
+ "json"
759
+ ]
713
760
  }
714
761
  },
762
+ "additionalProperties": false,
763
+ "oneOf": [
764
+ {
765
+ "required": [
766
+ "delimiter",
767
+ "format"
768
+ ],
769
+ "properties": {
770
+ "format": {
771
+ "const": "delimiter"
772
+ }
773
+ }
774
+ },
775
+ {
776
+ "properties": {
777
+ "format": {
778
+ "enum": [
779
+ "whole",
780
+ "lines",
781
+ "json"
782
+ ]
783
+ }
784
+ },
785
+ "not": {
786
+ "required": [
787
+ "delimiter"
788
+ ]
789
+ }
790
+ }
791
+ ]
792
+ },
793
+ "stdin": {
794
+ "description": "The normalized stdin axis of a flag or an arg.",
795
+ "type": "object",
715
796
  "required": [
716
- "value"
797
+ "consume",
798
+ "when"
717
799
  ],
718
- "description": "A selectable option for SelectPromptConfig and MultiselectPromptConfig prompts."
800
+ "properties": {
801
+ "consume": {
802
+ "description": "Whether this input consumes the stream alone.",
803
+ "enum": [
804
+ "exclusive",
805
+ "broadcast"
806
+ ]
807
+ },
808
+ "trim": {
809
+ "description": "Whether one trailing line terminator is dropped from a single value.",
810
+ "type": "boolean"
811
+ },
812
+ "when": {
813
+ "description": "When this input reads the stdin stream.",
814
+ "enum": [
815
+ "dash",
816
+ "missing",
817
+ "dash-or-missing"
818
+ ]
819
+ }
820
+ },
821
+ "additionalProperties": false
719
822
  },
720
- "example": {
823
+ "stringConstraints": {
721
824
  "type": "object",
722
- "additionalProperties": false,
723
825
  "properties": {
724
- "command": {
725
- "type": "string",
726
- "description": "The command invocation (e.g. `'deploy production --force'`)."
826
+ "maxLength": {
827
+ "type": "integer",
828
+ "minimum": 0
727
829
  },
728
- "description": {
729
- "type": "string",
730
- "description": "Optional description of what this example does."
830
+ "minLength": {
831
+ "type": "integer",
832
+ "minimum": 0
833
+ },
834
+ "nonEmpty": {
835
+ "type": "boolean"
836
+ },
837
+ "pattern": {
838
+ "type": "object",
839
+ "required": [
840
+ "flags",
841
+ "source"
842
+ ],
843
+ "properties": {
844
+ "flags": {
845
+ "type": "string"
846
+ },
847
+ "source": {
848
+ "type": "string"
849
+ }
850
+ },
851
+ "additionalProperties": false
731
852
  }
732
853
  },
733
- "required": [
734
- "command"
735
- ],
736
- "description": "A single usage example shown in help text."
854
+ "additionalProperties": false
737
855
  }
738
- }
856
+ },
857
+ "title": "@kjanat/dreamcli definition schema",
858
+ "description": "Runtime descriptor for the CLI program.\n\nStores the program name, version, description, and registered command schemas.\\\nSealed by createCLISchema and rebuilt by each CLIBuilder step.",
859
+ "type": "object",
860
+ "required": [
861
+ "$schema",
862
+ "commands",
863
+ "name",
864
+ "schemaVersion"
865
+ ],
866
+ "properties": {
867
+ "$schema": {
868
+ "const": "https://dreamcli.kjanat.dev/schemas/definition/v1.schema.json"
869
+ },
870
+ "commands": {
871
+ "description": "Schemas of the registered commands, in registration order.",
872
+ "type": "array",
873
+ "items": {
874
+ "$ref": "#/$defs/command"
875
+ }
876
+ },
877
+ "defaultCommand": {
878
+ "$ref": "#/$defs/command",
879
+ "description": "Schema of the default command dispatched when no subcommand matches.\n\nWhen set, the CLI root behaves like a hybrid command group: subcommands\ndispatch by name as usual, but empty argv or flags-only argv falls\nthrough to this command instead of showing root help.\n\nSet via the .default() builder method\nor the `defaultCommand` field of CLIDefinition."
880
+ },
881
+ "description": {
882
+ "description": "Program description (shown in root help).",
883
+ "type": "string"
884
+ },
885
+ "name": {
886
+ "description": "Program name (used in help text, usage lines, and completion scripts).",
887
+ "type": "string"
888
+ },
889
+ "schemaVersion": {
890
+ "const": 1
891
+ },
892
+ "version": {
893
+ "description": "Program version (shown by `--version`).",
894
+ "type": "string"
895
+ }
896
+ },
897
+ "additionalProperties": false
739
898
  }