@kjanat/dreamcli 3.0.1 → 4.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 (137) hide show
  1. package/CHANGELOG.md +962 -1
  2. package/README.md +7 -3
  3. package/dist/core/cli/builtins.d.mts +47 -0
  4. package/dist/core/cli/builtins.mjs +135 -0
  5. package/dist/core/cli/compiled.d.mts +29 -0
  6. package/dist/core/cli/compiled.mjs +76 -0
  7. package/dist/core/cli/dispatch.d.mts +9 -85
  8. package/dist/core/cli/help-links.d.mts +2 -14
  9. package/dist/core/cli/index.d.mts +282 -101
  10. package/dist/core/cli/index.mjs +497 -264
  11. package/dist/core/cli/planner.d.mts +13 -86
  12. package/dist/core/cli/planner.mjs +47 -30
  13. package/dist/core/cli/plugin.d.mts +1 -1
  14. package/dist/core/cli/propagate.mjs +1 -1
  15. package/dist/core/cli/reserved-flags.d.mts +1 -0
  16. package/dist/core/cli/reserved-flags.mjs +158 -0
  17. package/dist/core/cli/root-help.d.mts +1 -47
  18. package/dist/core/cli/root-help.mjs +37 -47
  19. package/dist/core/cli/root-output-flags.d.mts +1 -0
  20. package/dist/core/cli/root-output-flags.mjs +169 -0
  21. package/dist/core/cli/root-surface.d.mts +1 -68
  22. package/dist/core/cli/root-surface.mjs +2 -2
  23. package/dist/core/cli/runtime-preflight.d.mts +1 -199
  24. package/dist/core/cli/runtime-preflight.mjs +67 -17
  25. package/dist/core/completion/index.d.mts +2 -2
  26. package/dist/core/completion/shells/bash.d.mts +0 -1
  27. package/dist/core/completion/shells/bash.mjs +2 -1
  28. package/dist/core/completion/shells/fish.d.mts +0 -1
  29. package/dist/core/completion/shells/fish.mjs +2 -1
  30. package/dist/core/completion/shells/powershell.d.mts +0 -1
  31. package/dist/core/completion/shells/powershell.mjs +2 -1
  32. package/dist/core/completion/shells/shared.d.mts +3 -114
  33. package/dist/core/completion/shells/shared.mjs +9 -39
  34. package/dist/core/completion/shells/zsh.d.mts +0 -1
  35. package/dist/core/completion/shells/zsh.mjs +2 -1
  36. package/dist/core/config/index.d.mts +3 -3
  37. package/dist/core/config/index.mjs +2 -2
  38. package/dist/core/config/package-json.d.mts +2 -33
  39. package/dist/core/config/package-json.mjs +1 -34
  40. package/dist/core/errors/index.d.mts +7 -7
  41. package/dist/core/execution/index.d.mts +1 -48
  42. package/dist/core/execution/index.mjs +42 -27
  43. package/dist/core/help/ansi.d.mts +0 -11
  44. package/dist/core/help/index.d.mts +3 -35
  45. package/dist/core/help/index.mjs +29 -6
  46. package/dist/core/help/theme.d.mts +1 -21
  47. package/dist/core/json-schema/index.d.mts +279 -10
  48. package/dist/core/json-schema/index.mjs +482 -237
  49. package/dist/core/json-schema/meta-descriptions.generated.d.mts +79 -7
  50. package/dist/core/json-schema/meta-descriptions.generated.mjs +40 -6
  51. package/dist/core/output/activity.d.mts +1 -193
  52. package/dist/core/output/activity.mjs +1 -1
  53. package/dist/core/output/bind.d.mts +1 -37
  54. package/dist/core/output/contracts.d.mts +7 -13
  55. package/dist/core/output/contracts.mjs +1 -1
  56. package/dist/core/output/display-value.d.mts +1 -19
  57. package/dist/core/output/index.d.mts +5 -187
  58. package/dist/core/output/index.mjs +44 -9
  59. package/dist/core/output/renderers.d.mts +1 -45
  60. package/dist/core/output/writer.d.mts +0 -1
  61. package/dist/core/parse/index.d.mts +27 -5
  62. package/dist/core/parse/index.mjs +350 -227
  63. package/dist/core/parse/occurrences.d.mts +89 -0
  64. package/dist/core/parse/occurrences.mjs +114 -0
  65. package/dist/core/prompt/index.d.mts +3 -3
  66. package/dist/core/read-flags/index.d.mts +150 -0
  67. package/dist/core/read-flags/index.mjs +217 -0
  68. package/dist/core/resolve/args.d.mts +35 -4
  69. package/dist/core/resolve/args.mjs +132 -55
  70. package/dist/core/resolve/coerce.d.mts +66 -9
  71. package/dist/core/resolve/coerce.mjs +834 -270
  72. package/dist/core/resolve/config.d.mts +1 -10
  73. package/dist/core/resolve/contracts.d.mts +67 -44
  74. package/dist/core/resolve/errors.mjs +29 -21
  75. package/dist/core/resolve/flags.d.mts +36 -9
  76. package/dist/core/resolve/flags.mjs +129 -151
  77. package/dist/core/resolve/index.d.mts +8 -6
  78. package/dist/core/resolve/index.mjs +51 -18
  79. package/dist/core/resolve/path-checks.d.mts +47 -0
  80. package/dist/core/resolve/path-checks.mjs +102 -0
  81. package/dist/core/resolve/redaction.d.mts +12 -0
  82. package/dist/core/resolve/redaction.mjs +14 -0
  83. package/dist/core/resolve/stages.d.mts +85 -0
  84. package/dist/core/resolve/stages.mjs +170 -0
  85. package/dist/core/resolve/standard.d.mts +1 -24
  86. package/dist/core/resolve/standard.mjs +141 -43
  87. package/dist/core/schema/activity.d.mts +16 -16
  88. package/dist/core/schema/arg.d.mts +849 -71
  89. package/dist/core/schema/arg.mjs +727 -54
  90. package/dist/core/schema/brand.d.mts +17 -0
  91. package/dist/core/schema/cardinality.d.mts +301 -0
  92. package/dist/core/schema/cardinality.mjs +514 -0
  93. package/dist/core/schema/command.d.mts +173 -119
  94. package/dist/core/schema/command.mjs +305 -42
  95. package/dist/core/schema/flag.d.mts +515 -173
  96. package/dist/core/schema/flag.mjs +576 -78
  97. package/dist/core/schema/index.d.mts +11 -8
  98. package/dist/core/schema/index.mjs +10 -0
  99. package/dist/core/schema/middleware.d.mts +15 -12
  100. package/dist/core/schema/number-constraints.d.mts +5 -5
  101. package/dist/core/schema/prompt.d.mts +4 -4
  102. package/dist/core/schema/provenance.d.mts +99 -0
  103. package/dist/core/schema/provenance.mjs +28 -0
  104. package/dist/core/schema/run.d.mts +21 -60
  105. package/dist/core/schema/source.d.mts +179 -0
  106. package/dist/core/schema/source.mjs +206 -0
  107. package/dist/core/schema/standard.d.mts +12 -19
  108. package/dist/core/schema/stdin.d.mts +87 -0
  109. package/dist/core/schema/stdin.mjs +91 -0
  110. package/dist/core/schema/string-constraints.d.mts +16 -5
  111. package/dist/core/schema/string-constraints.mjs +18 -1
  112. package/dist/core/schema/value-parsers.d.mts +81 -9
  113. package/dist/core/schema/value-parsers.mjs +19 -1
  114. package/dist/core/schema/value.d.mts +242 -0
  115. package/dist/core/schema/value.mjs +573 -0
  116. package/dist/core/testkit/index.d.mts +30 -3
  117. package/dist/core/testkit/index.mjs +40 -26
  118. package/dist/index.d.mts +21 -16
  119. package/dist/index.mjs +10 -6
  120. package/dist/runtime/adapter.d.mts +3 -3
  121. package/dist/runtime/deno.d.mts +3 -3
  122. package/dist/runtime/detect.d.mts +2 -2
  123. package/dist/runtime/node.d.mts +3 -3
  124. package/dist/runtime/paths.d.mts +1 -31
  125. package/dist/runtime.d.mts +4 -4
  126. package/dist/strings.d.mts +1 -16
  127. package/dist/testkit.d.mts +2 -2
  128. package/dist/testkit.mjs +1 -1
  129. package/dist/version.d.mts +0 -13
  130. package/dist/version.mjs +2 -2
  131. package/dreamcli.schema.json +368 -78
  132. package/examples/interactive.ts +6 -5
  133. package/package.json +12 -11
  134. package/skills/cli-creation/SKILL.md +72 -16
  135. package/skills/cli-creation/references/pattern-cookbook.md +169 -11
  136. package/dist/core/resolve/property.d.mts +0 -51
  137. package/dist/core/resolve/property.mjs +0 -53
@@ -6,7 +6,7 @@
6
6
  */
7
7
  declare const definitionMetaSchemaDescriptions: {
8
8
  readonly root: {
9
- readonly description: "Runtime descriptor for the CLI program.\n\nStores the program name, version, description, and registered commands.\\\nBuilt incrementally by CLIBuilder.";
9
+ readonly description: "Runtime descriptor for the CLI program.\n\nStores the program name, version, description, and registered command schemas.\\\nSealed by createCLISchema and rebuilt by each CLIBuilder step.";
10
10
  readonly properties: {
11
11
  readonly name: {
12
12
  readonly description: "Program name (used in help text, usage lines, and completion scripts).";
@@ -18,16 +18,16 @@ declare const definitionMetaSchemaDescriptions: {
18
18
  readonly description: "Program description (shown in root help).";
19
19
  };
20
20
  readonly defaultCommand: {
21
- readonly description: "Default command dispatched when no subcommand matches.\n\nWhen set, the CLI root behaves like a hybrid command group: subcommands\ndispatch by name as usual, but empty argv or flags-only argv falls\nthrough to this command instead of showing root help.\n\nSet via the .default() builder method.";
21
+ readonly description: "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.";
22
22
  };
23
23
  readonly commands: {
24
- readonly description: "Registered commands (type-erased for heterogeneous storage).";
24
+ readonly description: "Schemas of the registered commands, in registration order.";
25
25
  };
26
26
  };
27
27
  };
28
28
  readonly defs: {
29
29
  readonly command: {
30
- readonly 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,\nmiddleware, and interactive resolver.";
30
+ readonly 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.";
31
31
  readonly properties: {
32
32
  readonly name: {
33
33
  readonly description: "The command name (used for dispatch, e.g. `'deploy'`).";
@@ -55,6 +55,38 @@ declare const definitionMetaSchemaDescriptions: {
55
55
  };
56
56
  };
57
57
  };
58
+ readonly commandDocument: {
59
+ readonly description: "A single-command definition document, version 1.\n\nProduced by generateCommandSchema. Same shape as a\nCommandDefinitionFragmentV1 plus the `schemaVersion` every standalone\ndocument carries.";
60
+ readonly properties: {
61
+ readonly schemaVersion: {
62
+ readonly description: "Version of the definition document format emitted by generateSchema\nand generateCommandSchema.";
63
+ };
64
+ readonly name: {
65
+ readonly description: "The command name used for dispatch.";
66
+ };
67
+ readonly description: {
68
+ readonly description: "Human-readable description for help text.";
69
+ };
70
+ readonly aliases: {
71
+ readonly description: "Alternative names accepted for this command.";
72
+ };
73
+ readonly hidden: {
74
+ readonly description: "Whether the command is omitted from help listings.";
75
+ };
76
+ readonly examples: {
77
+ readonly description: "Usage examples attached to the command.";
78
+ };
79
+ readonly flags: {
80
+ readonly description: "Named flag definitions keyed by flag name.";
81
+ };
82
+ readonly args: {
83
+ readonly description: "Positional argument definitions in CLI order.";
84
+ };
85
+ readonly commands: {
86
+ readonly description: "Nested subcommand definitions.";
87
+ };
88
+ };
89
+ };
58
90
  readonly flag: {
59
91
  readonly description: "The runtime descriptor stored inside every FlagBuilder. Consumers (parser,\nhelp generator, resolution chain) read this to understand the flag's shape\nwithout touching generics.";
60
92
  readonly properties: {
@@ -70,6 +102,9 @@ declare const definitionMetaSchemaDescriptions: {
70
102
  readonly aliases: {
71
103
  readonly description: "Short/long aliases (e.g. `[{ name: 'f', hidden: false }]` for `--force`).";
72
104
  };
105
+ readonly stdin: {
106
+ readonly description: "Stdin binding set by `.stdin()` (`undefined` when the flag never reads\nstdin). See StdinBinding.";
107
+ };
73
108
  readonly envVar: {
74
109
  readonly description: "Environment variable name for v0.2+ resolution.";
75
110
  };
@@ -83,7 +118,7 @@ declare const definitionMetaSchemaDescriptions: {
83
118
  readonly description: "Allowed literal values when `kind === 'enum'`.";
84
119
  };
85
120
  readonly elementSchema: {
86
- readonly description: "Element schema when `kind === 'array'`.";
121
+ readonly description: "Element schema when `kind === 'array'` or `kind === 'keyValue'`.";
87
122
  };
88
123
  readonly prompt: {
89
124
  readonly description: "Interactive prompt configuration for v0.3+ resolution.";
@@ -102,6 +137,20 @@ declare const definitionMetaSchemaDescriptions: {
102
137
  };
103
138
  };
104
139
  };
140
+ readonly stdin: {
141
+ readonly description: "The normalized stdin axis of a flag or an arg.";
142
+ readonly properties: {
143
+ readonly when: {
144
+ readonly description: "When this input reads the stdin stream.";
145
+ };
146
+ readonly consume: {
147
+ readonly description: "Whether this input consumes the stream alone.";
148
+ };
149
+ readonly trim: {
150
+ readonly description: "Whether one trailing line terminator is dropped from a single value.";
151
+ };
152
+ };
153
+ };
105
154
  readonly negation: {
106
155
  readonly 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.";
107
156
  readonly properties: {
@@ -128,8 +177,8 @@ declare const definitionMetaSchemaDescriptions: {
128
177
  readonly variadic: {
129
178
  readonly description: "Whether this arg consumes all remaining positionals.";
130
179
  };
131
- readonly stdinMode: {
132
- readonly description: "Whether this arg may read from stdin during resolution.\n\nDefault: `false`";
180
+ readonly stdin: {
181
+ readonly description: "Stdin binding set by `.stdin()` (`undefined` when the arg never reads\nstdin). See StdinBinding.";
133
182
  };
134
183
  readonly defaultValue: {
135
184
  readonly description: "Runtime default value (if any).";
@@ -140,14 +189,37 @@ declare const definitionMetaSchemaDescriptions: {
140
189
  readonly envVar: {
141
190
  readonly description: "Environment variable name for env resolution.\n\nWhen set and the CLI value is absent, the resolver reads this env var\nand coerces the string to the arg's declared kind.";
142
191
  };
192
+ readonly configPath: {
193
+ readonly description: "Dotted config path for config resolution (e.g. `'deploy.region'`).";
194
+ };
195
+ readonly prompt: {
196
+ readonly description: "Interactive prompt configuration.";
197
+ };
143
198
  readonly enumValues: {
144
199
  readonly description: "Allowed literal values when `kind === 'enum'`.";
145
200
  };
201
+ readonly elementSchema: {
202
+ readonly 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.";
203
+ };
146
204
  readonly deprecated: {
147
205
  readonly description: "Deprecation marker.\n\n- `undefined` — not deprecated (default)\n- `true` — deprecated with no migration message\n- `string` — deprecated with a reason/migration message\n\nWhen a deprecated arg is used, a warning is emitted to stderr.\nHelp text shows `[deprecated]` or `[deprecated: <reason>]`.";
148
206
  };
149
207
  };
150
208
  };
209
+ readonly argElement: {
210
+ readonly 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.";
211
+ readonly properties: {
212
+ readonly kind: {
213
+ readonly description: "What kind of value this arg accepts.";
214
+ };
215
+ readonly presence: {
216
+ readonly description: "Entry values are required once their containing key-value argument is present.";
217
+ };
218
+ readonly enumValues: {
219
+ readonly description: "Allowed literal values when `kind === 'enum'`.";
220
+ };
221
+ };
222
+ };
151
223
  readonly prompt: {
152
224
  readonly 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```";
153
225
  readonly properties: {
@@ -6,18 +6,18 @@
6
6
  */
7
7
  const definitionMetaSchemaDescriptions = {
8
8
  root: {
9
- description: "Runtime descriptor for the CLI program.\n\nStores the program name, version, description, and registered commands.\\\nBuilt incrementally by CLIBuilder.",
9
+ 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.",
10
10
  properties: {
11
11
  name: { description: "Program name (used in help text, usage lines, and completion scripts)." },
12
12
  version: { description: "Program version (shown by `--version`)." },
13
13
  description: { description: "Program description (shown in root help)." },
14
- defaultCommand: { description: "Default command dispatched when no subcommand matches.\n\nWhen set, the CLI root behaves like a hybrid command group: subcommands\ndispatch by name as usual, but empty argv or flags-only argv falls\nthrough to this command instead of showing root help.\n\nSet via the .default() builder method." },
15
- commands: { description: "Registered commands (type-erased for heterogeneous storage)." }
14
+ defaultCommand: { 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." },
15
+ commands: { description: "Schemas of the registered commands, in registration order." }
16
16
  }
17
17
  },
18
18
  defs: {
19
19
  command: {
20
- 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,\nmiddleware, and interactive resolver.",
20
+ 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.",
21
21
  properties: {
22
22
  name: { description: "The command name (used for dispatch, e.g. `'deploy'`)." },
23
23
  description: { description: "Human-readable description for help text." },
@@ -29,6 +29,20 @@ const definitionMetaSchemaDescriptions = {
29
29
  commands: { 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." }
30
30
  }
31
31
  },
32
+ commandDocument: {
33
+ description: "A single-command definition document, version 1.\n\nProduced by generateCommandSchema. Same shape as a\nCommandDefinitionFragmentV1 plus the `schemaVersion` every standalone\ndocument carries.",
34
+ properties: {
35
+ schemaVersion: { description: "Version of the definition document format emitted by generateSchema\nand generateCommandSchema." },
36
+ name: { description: "The command name used for dispatch." },
37
+ description: { description: "Human-readable description for help text." },
38
+ aliases: { description: "Alternative names accepted for this command." },
39
+ hidden: { description: "Whether the command is omitted from help listings." },
40
+ examples: { description: "Usage examples attached to the command." },
41
+ flags: { description: "Named flag definitions keyed by flag name." },
42
+ args: { description: "Positional argument definitions in CLI order." },
43
+ commands: { description: "Nested subcommand definitions." }
44
+ }
45
+ },
32
46
  flag: {
33
47
  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.",
34
48
  properties: {
@@ -36,11 +50,12 @@ const definitionMetaSchemaDescriptions = {
36
50
  presence: { 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)" },
37
51
  defaultValue: { description: "Runtime default value (if any)." },
38
52
  aliases: { description: "Short/long aliases (e.g. `[{ name: 'f', hidden: false }]` for `--force`)." },
53
+ stdin: { description: "Stdin binding set by `.stdin()` (`undefined` when the flag never reads\nstdin). See StdinBinding." },
39
54
  envVar: { description: "Environment variable name for v0.2+ resolution." },
40
55
  configPath: { description: "Dotted config path for v0.2+ resolution (e.g. `'deploy.region'`)." },
41
56
  description: { description: "Human-readable description for help text." },
42
57
  enumValues: { description: "Allowed literal values when `kind === 'enum'`." },
43
- elementSchema: { description: "Element schema when `kind === 'array'`." },
58
+ elementSchema: { description: "Element schema when `kind === 'array'` or `kind === 'keyValue'`." },
44
59
  prompt: { description: "Interactive prompt configuration for v0.3+ resolution." },
45
60
  deprecated: { 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>]`." },
46
61
  propagate: { 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`" },
@@ -48,6 +63,14 @@ const definitionMetaSchemaDescriptions = {
48
63
  duplicates: { 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'`" }
49
64
  }
50
65
  },
66
+ stdin: {
67
+ description: "The normalized stdin axis of a flag or an arg.",
68
+ properties: {
69
+ when: { description: "When this input reads the stdin stream." },
70
+ consume: { description: "Whether this input consumes the stream alone." },
71
+ trim: { description: "Whether one trailing line terminator is dropped from a single value." }
72
+ }
73
+ },
51
74
  negation: {
52
75
  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.",
53
76
  properties: {
@@ -62,14 +85,25 @@ const definitionMetaSchemaDescriptions = {
62
85
  kind: { description: "What kind of value this arg accepts." },
63
86
  presence: { 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)" },
64
87
  variadic: { description: "Whether this arg consumes all remaining positionals." },
65
- stdinMode: { description: "Whether this arg may read from stdin during resolution.\n\nDefault: `false`" },
88
+ stdin: { description: "Stdin binding set by `.stdin()` (`undefined` when the arg never reads\nstdin). See StdinBinding." },
66
89
  defaultValue: { description: "Runtime default value (if any)." },
67
90
  description: { description: "Human-readable description for help text." },
68
91
  envVar: { 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." },
92
+ configPath: { description: "Dotted config path for config resolution (e.g. `'deploy.region'`)." },
93
+ prompt: { description: "Interactive prompt configuration." },
69
94
  enumValues: { description: "Allowed literal values when `kind === 'enum'`." },
95
+ elementSchema: { 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." },
70
96
  deprecated: { 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>]`." }
71
97
  }
72
98
  },
99
+ argElement: {
100
+ 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.",
101
+ properties: {
102
+ kind: { description: "What kind of value this arg accepts." },
103
+ presence: { description: "Entry values are required once their containing key-value argument is present." },
104
+ enumValues: { description: "Allowed literal values when `kind === 'enum'`." }
105
+ }
106
+ },
73
107
  prompt: {
74
108
  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```",
75
109
  properties: {
@@ -1,193 +1 @@
1
- import { ActivityEvent, ProgressHandle, ProgressOptions, SpinnerHandle } from "../schema/activity.mjs";
2
- import { WriteFn } from "./writer.mjs";
3
- //#region src/core/output/activity.d.ts
4
- /**
5
- * Noop spinner handle singleton.
6
- *
7
- * All methods are no-ops. Used when spinners should produce no output
8
- * at all — `jsonMode`, or non-TTY with `fallback: 'silent'` (default).
9
- *
10
- * @internal
11
- */
12
- declare const noopSpinnerHandle: SpinnerHandle;
13
- /**
14
- * Noop progress handle singleton.
15
- *
16
- * All methods are no-ops. Used when progress bars should produce no
17
- * output at all — `jsonMode`, or non-TTY with `fallback: 'silent'`.
18
- *
19
- * @internal
20
- */
21
- declare const noopProgressHandle: ProgressHandle;
22
- /**
23
- * Static spinner handle — emits plain text at lifecycle boundaries.
24
- *
25
- * Used in non-TTY environments with `fallback: 'static'`. No animation,
26
- * no ANSI codes. Emits text on start and terminal events only.
27
- *
28
- * Terminal methods are idempotent — calling after stop is a no-op.
29
- *
30
- * @internal
31
- */
32
- declare class StaticSpinnerHandle implements SpinnerHandle {
33
- private readonly write;
34
- /** Whether the handle has been stopped (terminal state reached). */
35
- private stopped;
36
- constructor(text: string, write: WriteFn);
37
- update(_text: string): void;
38
- succeed(text?: string): void;
39
- fail(text?: string): void;
40
- stop(): void;
41
- wrap<T>(promise: Promise<T>, options?: {
42
- readonly succeed?: string;
43
- readonly fail?: string;
44
- }): Promise<T>;
45
- }
46
- /**
47
- * Static progress handle — emits plain text at lifecycle boundaries.
48
- *
49
- * Used in non-TTY environments with `fallback: 'static'`. No animation,
50
- * no progress bar rendering. Emits label on start, text on done/fail.
51
- *
52
- * Terminal methods are idempotent — calling after stop is a no-op.
53
- *
54
- * @internal
55
- */
56
- declare class StaticProgressHandle implements ProgressHandle {
57
- private readonly write;
58
- /** Whether the handle has been stopped (terminal state reached). */
59
- private stopped;
60
- constructor(label: string | undefined, write: WriteFn);
61
- increment(_n?: number): void;
62
- update(_value: number): void;
63
- done(text?: string): void;
64
- fail(text?: string): void;
65
- }
66
- /**
67
- * TTY spinner handle — animated braille frames with ANSI line overwrite.
68
- *
69
- * Used in TTY environments (non-JSON mode). Renders a spinning indicator
70
- * with configurable text, using `\r` + erase-line to overwrite in place.
71
- * Hides the cursor during animation and restores it on any terminal method.
72
- *
73
- * Terminal methods (`succeed`, `fail`, `stop`) are idempotent — calling any
74
- * of them after the handle is already stopped is a no-op.
75
- *
76
- * **Note:** If the process exits abnormally (e.g. `SIGKILL`) while a spinner
77
- * is active, the cursor may remain hidden. Use {@link SpinnerHandle.wrap} to
78
- * ensure cleanup on both success and failure paths.
79
- *
80
- * @internal
81
- */
82
- declare class TTYSpinnerHandle implements SpinnerHandle {
83
- private readonly write;
84
- /** Whether the handle has been stopped (terminal state reached). */
85
- private stopped;
86
- /** Animation timer handle — cleared on any terminal method. */
87
- private timer;
88
- /** Current position in the braille frame sequence. */
89
- private frameIndex;
90
- /** Current spinner text (mutable via `update()`). */
91
- private text;
92
- constructor(text: string, write: WriteFn);
93
- /** Render the current frame + text, overwriting the current line. */
94
- private render;
95
- /** Clear the animation timer, erase the line, and restore the cursor. */
96
- private cleanup;
97
- update(text: string): void;
98
- succeed(text?: string): void;
99
- fail(text?: string): void;
100
- stop(): void;
101
- wrap<T>(promise: Promise<T>, options?: {
102
- readonly succeed?: string;
103
- readonly fail?: string;
104
- }): Promise<T>;
105
- }
106
- /**
107
- * TTY progress handle — bar rendering with ANSI line overwrite.
108
- *
109
- * Supports two modes:
110
- * - **Determinate** (`total` provided) — renders `[████░░░░░░] 40% label`,
111
- * re-rendered on each `increment()` / `update()` call. No timer.
112
- * - **Indeterminate** (`total` omitted) — renders a pulsing highlight that
113
- * bounces across the bar via `setInterval`.
114
- *
115
- * Terminal methods (`done`, `fail`) are idempotent — calling any of them
116
- * after the handle is already stopped is a no-op.
117
- *
118
- * @internal
119
- */
120
- declare class TTYProgressHandle implements ProgressHandle {
121
- private readonly write;
122
- /** Whether the handle has been stopped (terminal state reached). */
123
- private stopped;
124
- /** Animation timer for indeterminate mode — `undefined` in determinate mode. */
125
- private timer;
126
- /** Current progress value (units completed). */
127
- private current;
128
- /** Total units of work (`undefined` = indeterminate mode). */
129
- private readonly total;
130
- /** Label displayed alongside the bar. */
131
- private readonly label;
132
- /** Pulse position for indeterminate animation (bouncing highlight). */
133
- private pulsePos;
134
- /** Pulse direction: 1 = forward, -1 = backward (for bounce). */
135
- private pulseDir;
136
- constructor(opts: ProgressOptions, write: WriteFn);
137
- /** Advance the indeterminate pulse position with bounce logic. */
138
- private advancePulse;
139
- /** Render the progress bar, overwriting the current line. */
140
- private render;
141
- /** Render a determinate bar: `[████░░░░░░] 40%`. */
142
- private renderDeterminate;
143
- /** Render an indeterminate bar: pulsing highlight bouncing across empty segments. */
144
- private renderIndeterminate;
145
- /** Clear the animation timer, erase the line, and restore the cursor. */
146
- private cleanup;
147
- increment(n?: number): void;
148
- update(value: number): void;
149
- done(text?: string): void;
150
- fail(text?: string): void;
151
- }
152
- /**
153
- * Spinner handle that records lifecycle events to a shared `ActivityEvent[]`.
154
- *
155
- * Used by `createCaptureOutput()` so testkit can assert on spinner behaviour
156
- * without polluting stdout/stderr arrays. Terminal methods are idempotent.
157
- *
158
- * @internal
159
- */
160
- declare class CaptureSpinnerHandle implements SpinnerHandle {
161
- private readonly events;
162
- /** Whether the handle has been stopped (terminal state reached). */
163
- private stopped;
164
- constructor(text: string, events: ActivityEvent[]);
165
- update(text: string): void;
166
- succeed(text?: string): void;
167
- fail(text?: string): void;
168
- stop(): void;
169
- wrap<T>(promise: Promise<T>, options?: {
170
- readonly succeed?: string;
171
- readonly fail?: string;
172
- }): Promise<T>;
173
- }
174
- /**
175
- * Progress handle that records lifecycle events to a shared `ActivityEvent[]`.
176
- *
177
- * Used by `createCaptureOutput()` so testkit can assert on progress behaviour
178
- * without polluting stdout/stderr arrays. Terminal methods are idempotent.
179
- *
180
- * @internal
181
- */
182
- declare class CaptureProgressHandle implements ProgressHandle {
183
- private readonly events;
184
- /** Whether the handle has been stopped (terminal state reached). */
185
- private stopped;
186
- constructor(opts: ProgressOptions, events: ActivityEvent[]);
187
- increment(n?: number): void;
188
- update(value: number): void;
189
- done(text?: string): void;
190
- fail(text?: string): void;
191
- }
192
- //#endregion
193
- export { CaptureProgressHandle, CaptureSpinnerHandle, StaticProgressHandle, StaticSpinnerHandle, TTYProgressHandle, TTYSpinnerHandle, noopProgressHandle, noopSpinnerHandle };
1
+ export {}
@@ -280,7 +280,7 @@ var TTYProgressHandle = class {
280
280
  this.pulsePos += this.pulseDir;
281
281
  if (this.pulsePos + PULSE_WIDTH > BAR_WIDTH) {
282
282
  this.pulseDir = -1;
283
- this.pulsePos = BAR_WIDTH - PULSE_WIDTH;
283
+ this.pulsePos = 17;
284
284
  } else if (this.pulsePos < 0) {
285
285
  this.pulseDir = 1;
286
286
  this.pulsePos = 0;
@@ -1,37 +1 @@
1
- //#region src/core/output/bind.d.ts
2
- /**
3
- * Method-binding helper for value objects handed to consumers.
4
- *
5
- * Output value objects — the `Out` channel and the spinner/progress handles
6
- * — expose methods that read instance state via `this`. Consumers naturally
7
- * detach those methods, either by destructuring
8
- * (`const { log } = out` / `const { succeed, fail } = spinner`) or by passing
9
- * them as callbacks (`promise.finally(spinner.stop)`). Detached, an unbound
10
- * prototype method loses its `this` and crashes on the first field access.
11
- *
12
- * {@linkcode bindMethods} eliminates that footgun by installing instance-bound
13
- * copies of every method, so the ergonomic usage is also the correct one.
14
- *
15
- * @module dreamcli/core/output/bind
16
- * @internal
17
- */
18
- /**
19
- * Bind every method on an instance's prototype chain to the instance.
20
- *
21
- * Walks the prototype chain up to (but excluding) `Object.prototype`, binding
22
- * each method name exactly once — the most-derived definition wins, so subclass
23
- * overrides (e.g. `CaptureOutputChannel.spinner`) are preserved rather than
24
- * clobbered by a base-class version. Bound methods are installed as
25
- * non-enumerable own properties, mirroring the enumerability of the prototype
26
- * methods they shadow. Getters and non-function members are left untouched.
27
- *
28
- * Call this once, last, in a class constructor. Because it reads the live
29
- * prototype rather than a hand-maintained name list, methods added later are
30
- * bound automatically — the binding can't silently fall out of date.
31
- *
32
- * @param instance - The object whose methods should be bound to it.
33
- * @internal
34
- */
35
- declare function bindMethods(instance: object): void;
36
- //#endregion
37
- export { bindMethods };
1
+ export {}
@@ -1,4 +1,3 @@
1
- import { Fallback, TableOptions } from "../schema/activity.mjs";
2
1
  //#region src/core/output/contracts.d.ts
3
2
  /** Ordered output verbosity levels owned by the output policy layer. */
4
3
  declare const OUTPUT_VERBOSITY_LEVELS: readonly ["normal", "quiet"];
@@ -37,9 +36,9 @@ interface ResolveOutputPolicyOptions {
37
36
  /** Concrete activity policy chosen for spinner/progress creation. */
38
37
  interface ActivityPolicy {
39
38
  /** Render strategy for the activity indicator (never `'capture'` here). */
40
- readonly mode: Exclude<ActivityRenderMode, 'capture'>;
39
+ readonly mode: Exclude<ActivityRenderMode, "capture">;
41
40
  /** Activity output always targets stderr to avoid polluting structured stdout. */
42
- readonly stream: 'stderr';
41
+ readonly stream: "stderr";
43
42
  /** Cleanup action the output layer must run when the handle is discarded. */
44
43
  readonly cleanup: ActivityCleanupKind;
45
44
  }
@@ -49,6 +48,8 @@ interface OutputContract {
49
48
  readonly jsonReservesStdoutForStructuredData: true;
50
49
  /** Quiet verbosity suppresses `info()` messages entirely. */
51
50
  readonly quietSuppressesInfo: true;
51
+ /** Quiet verbosity suppresses rendered spinner/progress output; capture still records lifecycle events. */
52
+ readonly quietSuppressesRenderedActivity: true;
52
53
  /** Spinner/progress writes go to stderr so stdout stays parseable. */
53
54
  readonly activityUsesStderrOutsideCapture: true;
54
55
  /** Animated TTY spinners require both a real terminal and non-JSON mode. */
@@ -59,14 +60,7 @@ interface OutputContract {
59
60
  readonly progressCleanupUsesDone: true;
60
61
  }
61
62
  /** Runtime-accessible copy of the frozen output-policy invariants. */
62
- declare const outputContract: {
63
- jsonReservesStdoutForStructuredData: true;
64
- quietSuppressesInfo: true;
65
- activityUsesStderrOutsideCapture: true;
66
- ttyActivityRequiresTTYAndNonJson: true;
67
- spinnerCleanupUsesStop: true;
68
- progressCleanupUsesDone: true;
69
- };
63
+ declare const outputContract: OutputContract;
70
64
  /** Build the stable output-policy snapshot for one channel instance. */
71
65
  declare function resolveOutputPolicy(options: ResolveOutputPolicyOptions): OutputPolicy;
72
66
  /** Resolve the default text stream for non-JSON structured output. */
@@ -74,11 +68,11 @@ declare function resolveTextStream(policy: OutputPolicy): OutputStream;
74
68
  /** Whether `info()`/`status()` messages should be emitted under the current policy. */
75
69
  declare function shouldEmitInfo(policy: OutputPolicy): boolean;
76
70
  /** Resolve the concrete table format under the current policy. */
77
- declare function resolveTableFormat(policy: OutputPolicy, options?: TableOptions): 'text' | 'json';
71
+ declare function resolveTableFormat(policy: OutputPolicy, options?: TableOptions): "text" | "json";
78
72
  /** Resolve the text-table stream after table-format selection. */
79
73
  declare function resolveTableTextStream(policy: OutputPolicy, options?: TableOptions): OutputStream;
80
74
  /** Resolve the non-capture activity mode shared by spinner and progress. */
81
- declare function resolveActivityRenderMode(policy: OutputPolicy, fallback: Fallback): ActivityPolicy['mode'];
75
+ declare function resolveActivityRenderMode(policy: OutputPolicy, fallback: Fallback): ActivityPolicy["mode"];
82
76
  /** Resolve spinner activity policy including cleanup ownership. */
83
77
  declare function resolveSpinnerPolicy(policy: OutputPolicy, fallback: Fallback): ActivityPolicy;
84
78
  /** Resolve progress activity policy including cleanup ownership. */
@@ -31,7 +31,7 @@ function resolveTableTextStream(policy, options) {
31
31
  }
32
32
  /** Resolve the non-capture activity mode shared by spinner and progress. */
33
33
  function resolveActivityRenderMode(policy, fallback) {
34
- if (policy.jsonMode) return "noop";
34
+ if (policy.jsonMode || policy.verbosity === "quiet") return "noop";
35
35
  if (policy.isTTY) return "tty";
36
36
  return fallback === "static" ? "static" : "noop";
37
37
  }
@@ -1,19 +1 @@
1
- //#region src/core/output/display-value.d.ts
2
- /**
3
- * Shared runtime-value formatting for human-readable output.
4
- *
5
- * Used by help text and table rendering so default values and structured cells
6
- * stringify consistently across the CLI surface.
7
- *
8
- * @module dreamcli/core/output/display-value
9
- * @internal
10
- */
11
- /**
12
- * Format an unknown runtime value for human-readable output.
13
- *
14
- * @param value - The value to format (any type).
15
- * @returns A string representation suitable for table cells and help text.
16
- */
17
- declare function formatDisplayValue(value: unknown): string;
18
- //#endregion
19
- export { formatDisplayValue };
1
+ export {}