@kjanat/dreamcli 4.0.0-rc.3 → 4.1.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-YM5QGi3M.d.mts} +4 -4
  3. package/dist/completion-CUMeOnAz.mjs +6 -0
  4. package/dist/completion.d.mts +90 -0
  5. package/dist/completion.mjs +1 -0
  6. package/dist/config-CrlScpYX.mjs +1 -0
  7. package/dist/config.d.mts +2 -0
  8. package/dist/config.mjs +1 -0
  9. package/dist/core-DvXUolc_.mjs +17 -0
  10. package/dist/{core/json-schema/index.d.mts → index-3l8uj16E.d.mts} +43 -34
  11. package/dist/{core/cli/index.d.mts → index-BAj2y70U.d.mts} +116 -57
  12. package/dist/index-BziI2aKc.d.mts +5440 -0
  13. package/dist/index-Cap0MA2V.d.mts +277 -0
  14. package/dist/index-Cp9kt2t-.d.mts +370 -0
  15. package/dist/index-DWsnGZlx.d.mts +831 -0
  16. package/dist/index.d.mts +190 -41
  17. package/dist/index.mjs +1 -26
  18. package/dist/json-schema-DRlrz_IV.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,418 +0,0 @@
1
- import { getFlagAliasNames } from "../schema/flag.mjs";
2
- import { resolveExampleCommand } from "../schema/command.mjs";
3
- import { extendHelpTheme, resolveHelpDescription, resolveHelpTheme } from "./theme.mjs";
4
- import { formatDisplayValue } from "../output/display-value.mjs";
5
- import { osc8, padEnd, visibleWidth, wrapText } from "./ansi.mjs";
6
- //#region src/core/help/index.ts
7
- const DEFAULT_WIDTH = 80;
8
- /**
9
- * Apply defaults to optional {@link HelpOptions}.
10
- *
11
- * @param options - User-supplied help options, or `undefined` for all defaults.
12
- * @returns Fully resolved options with defaults applied.
13
- */
14
- function resolveOptions(options) {
15
- const theme = resolveHelpTheme(options?.colors, options?.theme);
16
- return {
17
- width: options?.width ?? DEFAULT_WIDTH,
18
- binName: options?.binName,
19
- version: options?.version,
20
- flagOrder: options?.flagOrder ?? "alphabetical",
21
- sortFlags: options?.sortFlags,
22
- isDefaultHelp: options?.isDefaultHelp ?? false,
23
- theme,
24
- descriptionTheme: extendHelpTheme(theme, options?.colors, options?.descriptionTheme)
25
- };
26
- }
27
- /**
28
- * Format a deprecation annotation for help text.
29
- *
30
- * @param deprecated - `true` for a generic marker, or a string explaining the deprecation.
31
- * @returns Bracketed deprecation label, e.g. `[deprecated]` or `[deprecated: use --foo]`.
32
- */
33
- function formatDeprecated(deprecated) {
34
- return typeof deprecated === "string" ? `[deprecated: ${deprecated}]` : "[deprecated]";
35
- }
36
- /** Format a default value for help output, preserving nullish sentinels. */
37
- function formatHelpDefaultValue(value) {
38
- if (value === void 0) return "undefined";
39
- if (value === null) return "null";
40
- return formatDisplayValue(value);
41
- }
42
- /**
43
- * Format a flag's left column: `-a, --name <type>`.
44
- *
45
- * @param name - Long flag name (without `--` prefix).
46
- * @param schema - The {@link FlagSchema} describing the flag.
47
- * @param theme - Theme applied to the flag forms and value hint.
48
- * @returns Formatted left-column string for the flags table.
49
- */
50
- function formatFlagLeft(name, schema, theme) {
51
- const visibleShortAliases = getFlagAliasNames(schema, { kind: "short" });
52
- const visibleLongAliases = getFlagAliasNames(schema, { kind: "long" });
53
- const negation = schema.negation !== void 0 && !schema.negation.hidden ? schema.negation : void 0;
54
- const canonicalForm = negation !== void 0 && negation.alias === void 0 ? `--[no-]${name}` : `--${name}`;
55
- const forms = [
56
- ...visibleShortAliases.map((alias) => `-${alias}`),
57
- canonicalForm,
58
- ...visibleLongAliases.map((alias) => `--${alias}`),
59
- ...negation?.alias !== void 0 ? [`--${negation.alias}`] : []
60
- ];
61
- if (schema.kind !== "boolean" && schema.kind !== "count") return `${theme.flag(forms.join(", "))} ${theme.placeholder(formatValueHint(schema))}`;
62
- return theme.flag(forms.join(", "));
63
- }
64
- /**
65
- * Produce a type hint like `<string>`, `<number>`, `<us|eu|ap>`.
66
- *
67
- * A schema-level `valueHint` (set by sugar factories like `flag.url()`)
68
- * overrides the kind-derived hint.
69
- *
70
- * @param schema - The {@link FlagSchema} whose value type determines the hint.
71
- * @returns Angle-bracketed hint string, or empty string for no-value kinds.
72
- */
73
- function formatValueHint(schema) {
74
- if (schema.valueHint !== void 0) return `<${schema.valueHint}>`;
75
- switch (schema.kind) {
76
- case "string": return "<string>";
77
- case "number": return "<number>";
78
- case "enum": return `<${(schema.enumValues ?? []).join("|")}>`;
79
- case "array": return `<${schema.elementSchema !== void 0 ? formatValueHint(schema.elementSchema).slice(1, -1) : "value"}>...`;
80
- case "boolean":
81
- case "count": return "";
82
- case "custom": return "<value>";
83
- case "keyValue": return "<key=value>";
84
- }
85
- }
86
- /**
87
- * Name what selects the stdin stream for an input, in the `[env: X]` style.
88
- *
89
- * `[stdin]` covers the default trigger, where both an explicit `-` and an
90
- * absent input read the stream. The narrower triggers say which one applies, so
91
- * a reader knows whether typing `-` is required.
92
- *
93
- * @param stdin - The input's stdin axis.
94
- * @returns The annotation to render beside the description.
95
- */
96
- function formatStdinAnnotation(stdin) {
97
- switch (stdin.when) {
98
- case "dash": return "[stdin: '-']";
99
- case "missing": return "[stdin: when omitted]";
100
- case "dash-or-missing": return "[stdin]";
101
- }
102
- }
103
- /**
104
- * Build description with stdin/env/config/prompt/default/required/deprecated
105
- * annotations.
106
- *
107
- * @param schema - The {@link FlagSchema} to describe.
108
- * @param theme - Theme applied to the metadata annotations.
109
- * @param descriptionTheme - Theme passed to a function-form description.
110
- * @returns Concatenated description string with metadata annotations.
111
- */
112
- function formatFlagDescription(schema, theme, descriptionTheme) {
113
- const parts = [];
114
- if (schema.description !== void 0) parts.push(resolveHelpDescription(schema.description, descriptionTheme));
115
- if (schema.deprecated !== void 0) parts.push(theme.deprecated(formatDeprecated(schema.deprecated)));
116
- if (schema.stdin !== void 0) parts.push(theme.annotation(formatStdinAnnotation(schema.stdin)));
117
- if (schema.envVar !== void 0) parts.push(theme.annotation(`[env: ${schema.envVar}]`));
118
- if (schema.configPath !== void 0) parts.push(theme.annotation(`[config: ${schema.configPath}]`));
119
- if (schema.prompt !== void 0) parts.push(theme.annotation("[prompt]"));
120
- if (schema.presence === "required" && schema.defaultValue === void 0) parts.push(theme.annotation("[required]"));
121
- else if ((schema.presence === "defaulted" || schema.defaultValue !== void 0) && schema.kind !== "boolean" && schema.kind !== "count") parts.push(theme.defaultValue(`(default: ${formatHelpDefaultValue(schema.defaultValue)})`));
122
- return parts.join(" ");
123
- }
124
- /**
125
- * Default flag order: short-aliased flags first, then alphabetical by name.
126
- */
127
- function defaultFlagOrder(a, b, flags) {
128
- const aSchema = flags[a];
129
- const bSchema = flags[b];
130
- if (aSchema === void 0 || bSchema === void 0) return 0;
131
- const aHasShort = getFlagAliasNames(aSchema, { kind: "short" }).length > 0;
132
- const bHasShort = getFlagAliasNames(bSchema, { kind: "short" }).length > 0;
133
- if (aHasShort && !bHasShort) return -1;
134
- if (!aHasShort && bHasShort) return 1;
135
- return a.localeCompare(b);
136
- }
137
- /**
138
- * Order flag names for the table: an explicit `sortFlags` comparator wins,
139
- * then `'declaration'` preserves `.flag()` call order, otherwise the default
140
- * short-first alphabetical order.
141
- */
142
- function orderFlagNames(names, flags, opts) {
143
- if (opts.sortFlags !== void 0) return [...names].sort(opts.sortFlags);
144
- if (opts.flagOrder === "declaration") return names;
145
- return [...names].sort((a, b) => defaultFlagOrder(a, b, flags));
146
- }
147
- /**
148
- * Build the flag entries in the configured order.
149
- *
150
- * @param flags - Map of flag names to {@link FlagSchema} definitions.
151
- * @param opts - Resolved help options (theme + flag ordering).
152
- * @returns Array of {@link FlagEntry} objects for the flags table.
153
- */
154
- function buildFlagEntries(flags, opts) {
155
- const names = Object.keys(flags);
156
- if (names.length === 0) return [];
157
- const entries = [];
158
- for (const name of orderFlagNames(names, flags, opts)) {
159
- const schema = flags[name];
160
- if (schema === void 0) continue;
161
- entries.push({
162
- left: formatFlagLeft(name, schema, opts.theme),
163
- description: formatFlagDescription(schema, opts.theme, opts.descriptionTheme)
164
- });
165
- }
166
- return entries;
167
- }
168
- /**
169
- * Format a positional arg for the usage line.
170
- *
171
- * @param entry - The {@link CommandArgEntry} containing name and schema.
172
- * @returns Bracketed arg token, e.g. `<file>` or `[output]...`.
173
- */
174
- function formatArgUsage(entry) {
175
- const { name, schema } = entry;
176
- const label = schema.kind === "enum" && schema.enumValues !== void 0 ? schema.enumValues.join("|") : name;
177
- const variadicSuffix = schema.variadic ? "..." : "";
178
- if (schema.presence === "required" && schema.defaultValue === void 0) return `<${label}>${variadicSuffix}`;
179
- return `[${label}]${variadicSuffix}`;
180
- }
181
- /**
182
- * Format arg description with stdin/env/config/prompt/default/deprecated
183
- * annotations.
184
- *
185
- * @param schema - The {@link ArgSchema} to describe.
186
- * @param theme - Theme applied to the metadata annotations.
187
- * @param descriptionTheme - Theme passed to a function-form description.
188
- * @returns Concatenated description string with metadata annotations.
189
- */
190
- function formatArgDescription(schema, theme, descriptionTheme) {
191
- const parts = [];
192
- if (schema.description !== void 0) parts.push(resolveHelpDescription(schema.description, descriptionTheme));
193
- if (schema.deprecated !== void 0) parts.push(theme.deprecated(formatDeprecated(schema.deprecated)));
194
- if (schema.stdin !== void 0) parts.push(theme.annotation(formatStdinAnnotation(schema.stdin)));
195
- if (schema.envVar !== void 0) parts.push(theme.annotation(`[env: ${schema.envVar}]`));
196
- if (schema.configPath !== void 0) parts.push(theme.annotation(`[config: ${schema.configPath}]`));
197
- if (schema.prompt !== void 0) parts.push(theme.annotation("[prompt]"));
198
- if (schema.presence === "defaulted" || schema.defaultValue !== void 0) parts.push(theme.defaultValue(`(default: ${formatHelpDefaultValue(schema.defaultValue)})`));
199
- return parts.join(" ");
200
- }
201
- /**
202
- * Build the ordered help sections without joining them.
203
- *
204
- * @internal
205
- * @param schema - The {@link CommandSchema} to render.
206
- * @param options - Optional {@link HelpOptions} for width/bin name.
207
- * @returns Array of section strings (usage, description, commands, args, flags, examples).
208
- */
209
- function formatHelpSections(schema, options) {
210
- const opts = resolveOptions(options);
211
- const sections = [];
212
- sections.push(formatUsageLine(schema, opts));
213
- if (schema.description !== void 0) sections.push(schema.description);
214
- const visibleCommands = schema.commands.filter((c) => !c.hidden);
215
- if (visibleCommands.length > 0) sections.push(formatCommandsSection(visibleCommands, opts));
216
- if (schema.args.length > 0) sections.push(formatArgsSection(schema.args, opts));
217
- if (Object.keys(schema.flags).length > 0) sections.push(formatFlagsSection(schema.flags, opts));
218
- if (schema.examples.length > 0) {
219
- const meta = {
220
- name: opts.binName ?? schema.name,
221
- version: opts.version
222
- };
223
- sections.push(formatExamplesSection(schema.examples, opts.theme, meta));
224
- }
225
- return sections;
226
- }
227
- /**
228
- * Generate help text from a command schema.
229
- *
230
- * Low-level formatter: most applications reach this through `--help`,
231
- * `help <command>`, or root help rendering in `CLIBuilder`. Call
232
- * `formatHelp()` directly when embedding DreamCLI help text into custom UIs,
233
- * tests, or generated docs.
234
- *
235
- * Sections rendered (in order):
236
- * 1. **Usage** line — `program <command> [flags] <args>`
237
- * 2. **Description** — the command's `.description()` text
238
- * 3. **Commands** — subcommands table (if any, skips hidden)
239
- * 4. **Arguments** — positional args table (if any)
240
- * 5. **Flags** — flags table with type hints and defaults
241
- * 6. **Examples** — usage examples (if any)
242
- *
243
- * @param schema - The command schema to render help for.
244
- * @param options - Formatting options (width, binary name).
245
- * @returns The formatted help string.
246
- *
247
- * @example
248
- * ```ts
249
- * const text = formatHelp(deploy.schema, { binName: 'mycli' });
250
- * ```
251
- */
252
- function formatHelp(schema, options) {
253
- return `${formatHelpSections(schema, options).join("\n\n")}\n`;
254
- }
255
- /**
256
- * Render the `Usage:` line for a command.
257
- *
258
- * @param schema - The {@link CommandSchema} to summarize.
259
- * @param opts - Resolved help options (bin name, default-help flag).
260
- * @returns Single-line usage string, e.g. `Usage: mycli deploy [flags] <env>`.
261
- */
262
- function formatUsageLine(schema, opts) {
263
- const { theme } = opts;
264
- const parts = [theme.sectionTitle("Usage:")];
265
- const cmdName = opts.binName === void 0 ? schema.name : opts.isDefaultHelp ? opts.binName : `${opts.binName} ${schema.name}`;
266
- parts.push(theme.usageBin(cmdName));
267
- if (schema.commands.length > 0) parts.push(theme.placeholder("<command>"));
268
- if (Object.keys(schema.flags).length > 0) parts.push(theme.placeholder("[flags]"));
269
- for (const entry of schema.args) parts.push(theme.arg(formatArgUsage(entry)));
270
- return parts.join(" ");
271
- }
272
- /**
273
- * Render the `Arguments:` help section.
274
- *
275
- * @param args - Positional arg entries from the {@link CommandSchema}.
276
- * @param opts - Resolved help options for line-width wrapping.
277
- * @returns Multi-line arguments section string.
278
- */
279
- function formatArgsSection(args, opts) {
280
- const { theme } = opts;
281
- const lines = [theme.sectionTitle("Arguments:")];
282
- const GAP = 2;
283
- let maxLeft = 0;
284
- const entries = [];
285
- for (const entry of args) {
286
- const left = ` ${theme.arg(formatArgUsage(entry))}`;
287
- const desc = formatArgDescription(entry.schema, theme, opts.descriptionTheme);
288
- entries.push({
289
- left,
290
- desc
291
- });
292
- const leftWidth = visibleWidth(left);
293
- if (leftWidth > maxLeft) maxLeft = leftWidth;
294
- }
295
- const descCol = maxLeft + GAP;
296
- for (const { left, desc } of entries) if (desc.length === 0) lines.push(left);
297
- else {
298
- const padded = padEnd(left, descCol);
299
- const wrapped = wrapText(desc, opts.width, descCol);
300
- lines.push(`${padded}${wrapped}`);
301
- }
302
- return lines.join("\n");
303
- }
304
- /**
305
- * Render the `Flags:` help section.
306
- *
307
- * @param flags - Map of flag names to {@link FlagSchema} definitions.
308
- * @param opts - Resolved help options for line-width wrapping.
309
- * @returns Multi-line flags section string.
310
- */
311
- function formatFlagsSection(flags, opts) {
312
- return formatFlagEntriesBlock(opts.theme.sectionTitle("Flags:"), buildFlagEntries(flags, opts), opts.width);
313
- }
314
- /**
315
- * Render a titled two-column flag block from pre-built {@link FlagEntry} rows.
316
- *
317
- * Shared by the per-command `Flags:` section and the root-help `Global options:`
318
- * block (built-in flags), so column alignment and description wrapping stay
319
- * identical across both. Returns `''` when there are no entries.
320
- *
321
- * @param title - Section heading (e.g. `'Flags:'`, `'Global options:'`), pre-styled by the caller.
322
- * @param entries - Formatted left/description rows.
323
- * @param width - Terminal width for description wrapping.
324
- * @returns Multi-line block string, or `''` when `entries` is empty.
325
- * @internal
326
- */
327
- function formatFlagEntriesBlock(title, entries, width) {
328
- if (entries.length === 0) return "";
329
- const lines = [title];
330
- const GAP = 2;
331
- let maxLeft = 0;
332
- for (const entry of entries) {
333
- const indentedWidth = visibleWidth(entry.left) + 2;
334
- if (indentedWidth > maxLeft) maxLeft = indentedWidth;
335
- }
336
- const descCol = maxLeft + GAP;
337
- for (const entry of entries) {
338
- const left = ` ${entry.left}`;
339
- if (entry.description.length === 0) lines.push(left);
340
- else {
341
- const padded = padEnd(left, descCol);
342
- const wrapped = wrapText(entry.description, width, descCol);
343
- lines.push(`${padded}${wrapped}`);
344
- }
345
- }
346
- return lines.join("\n");
347
- }
348
- /**
349
- * Render the `Commands:` help section.
350
- *
351
- * @param commands - Visible subcommand schemas (hidden commands pre-filtered).
352
- * @param opts - Resolved help options for line-width wrapping.
353
- * @returns Multi-line commands section string.
354
- */
355
- function formatCommandsSection(commands, opts) {
356
- const { theme } = opts;
357
- const lines = [theme.sectionTitle("Commands:")];
358
- const GAP = 2;
359
- let maxNameLen = 0;
360
- for (const cmd of commands) if (cmd.name.length > maxNameLen) maxNameLen = cmd.name.length;
361
- const descCol = 2 + maxNameLen + GAP;
362
- for (const cmd of commands) {
363
- const left = ` ${theme.command(cmd.name)}`;
364
- const desc = cmd.description ?? "";
365
- if (desc.length === 0) lines.push(left);
366
- else {
367
- const padded = padEnd(left, descCol);
368
- const wrapped = wrapText(desc, opts.width, descCol);
369
- lines.push(`${padded}${wrapped}`);
370
- }
371
- }
372
- return lines.join("\n");
373
- }
374
- /**
375
- * One shell token: a single- or double-quoted span (kept whole so internal
376
- * spaces don't split it) or a run of non-whitespace characters.
377
- */
378
- const EXAMPLE_TOKEN = /(?:'[^']*'|"[^"]*"|\S)+/g;
379
- /**
380
- * Highlight an example command per token: the leading binary via `usageBin`,
381
- * flag tokens (`-x`, `--long`) via `flag`, everything else plain.
382
- *
383
- * Uses `replace` so only the token spans are wrapped and the whitespace
384
- * between them is preserved verbatim — with the color gate off (identity
385
- * formatters) the result equals `command`, so `stripAnsi(highlighted)` stays
386
- * equal to the plain rendering.
387
- */
388
- function highlightExampleCommand(command, theme) {
389
- let index = 0;
390
- return command.replace(EXAMPLE_TOKEN, (token) => {
391
- const styled = index === 0 ? theme.usageBin(token) : token.startsWith("-") ? theme.flag(token) : token;
392
- index += 1;
393
- return styled;
394
- });
395
- }
396
- /**
397
- * Render the `Examples:` help section.
398
- *
399
- * @param examples - Array of {@link CommandExample} entries.
400
- * @param theme - Theme applied to the section title, `$` prompt marker, and
401
- * per-token command highlighting.
402
- * @param meta - Program name/version passed to function-form example commands.
403
- * @returns Multi-line examples section string.
404
- */
405
- function formatExamplesSection(examples, theme, meta) {
406
- const lines = [theme.sectionTitle("Examples:")];
407
- const prompt = theme.examplePrompt("$");
408
- for (const example of examples) {
409
- const command = highlightExampleCommand(resolveExampleCommand(example.command, meta), theme);
410
- if (example.description !== void 0) {
411
- lines.push(` ${example.description}:`);
412
- lines.push(` ${prompt} ${command}`);
413
- } else lines.push(` ${prompt} ${command}`);
414
- }
415
- return lines.join("\n");
416
- }
417
- //#endregion
418
- export { formatFlagEntriesBlock, formatHelp, formatHelpSections, osc8, visibleWidth };
@@ -1,86 +0,0 @@
1
- import { Colors, Formatter } from "ansispeck";
2
- //#region src/core/help/theme.d.ts
3
- /**
4
- * Semantic styling roles for help output.
5
- *
6
- * Roles that appear inside wrap-eligible description text (`defaultValue`,
7
- * `annotation`, `deprecated`) should stick to foreground colors and `dim` —
8
- * a styled span may cross a soft-wrap boundary, and while color/dim carry
9
- * invisibly across the continuation indent, `underline`/`inverse`/background
10
- * styles would visibly paint it.
11
- */
12
- interface HelpTheme {
13
- /** Section headings: `Usage:`, `Arguments:`, `Flags:`, `Commands:`, `Examples:`, `Global options:`. */
14
- readonly sectionTitle: Formatter;
15
- /** Binary / command path in the usage line. */
16
- readonly usageBin: Formatter;
17
- /** Flag forms in the flags table: `-f, --force`. */
18
- readonly flag: Formatter;
19
- /** Grammar tokens: `<string>`, `<command>`, `[flags]`, value hints. */
20
- readonly placeholder: Formatter;
21
- /** Command names in `Commands:` tables. */
22
- readonly command: Formatter;
23
- /** Positional arg tokens: `<file>`, `[out]...`. */
24
- readonly arg: Formatter;
25
- /** Default-value annotations: `(default: 8080)`. */
26
- readonly defaultValue: Formatter;
27
- /** Metadata annotations: `[env: X]`, `[config: a.b]`, `[prompt]`, `[required]`, ` (default)`. */
28
- readonly annotation: Formatter;
29
- /** Deprecation labels: `[deprecated]`, `[deprecated: use --x]`. */
30
- readonly deprecated: Formatter;
31
- /** Program name in the root-help header. */
32
- readonly headerName: Formatter;
33
- /** Version (`vX.Y.Z`) in the root-help header. */
34
- readonly headerVersion: Formatter;
35
- /** The `$` prompt marker in `Examples:`. */
36
- readonly examplePrompt: Formatter;
37
- }
38
- /**
39
- * Help description text, either literal or resolved against the effective
40
- * description theme at render time.
41
- */
42
- type HelpDescription = string | ((theme: HelpTheme) => string);
43
- /**
44
- * User theme customization: receives the gated palette and returns role
45
- * overrides merged over the default theme.
46
- *
47
- * The palette formatters are identity functions when color is disabled, and
48
- * the factory itself is only invoked when color is enabled — style
49
- * unconditionally, gating is the framework's job.
50
- */
51
- type HelpThemeFactory = (colors: Colors) => Partial<HelpTheme>;
52
- /**
53
- * The built-in help theme (clap/cargo conventions).
54
- *
55
- * @param c - Palette to build formatters from (typically the gated `out.color`).
56
- * @internal
57
- */
58
- declare function defaultHelpTheme(c: Colors): HelpTheme;
59
- /**
60
- * Resolve the effective help theme from a palette and optional user factory.
61
- *
62
- * When the palette renders no styling (color disabled — its formatters are
63
- * identity functions), the user factory is **never invoked**: even a factory
64
- * that emits raw escapes cannot leak them into color-off output. When color
65
- * is enabled, factory overrides merge over {@linkcode defaultHelpTheme}.
66
- *
67
- * @param colors - Gated palette, or `undefined` for a color-off theme.
68
- * @param theme - Optional user overrides factory.
69
- * @internal
70
- */
71
- declare function resolveHelpTheme(colors: Colors | undefined, theme: HelpThemeFactory | undefined): HelpTheme;
72
- /**
73
- * Merge a scoped theme factory over an already-resolved help theme.
74
- *
75
- * The scoped factory follows the same color gate as the global factory and is
76
- * never invoked when the palette is disabled.
77
- *
78
- * @internal
79
- */
80
- declare function extendHelpTheme(theme: HelpTheme, colors: Colors | undefined, override: HelpThemeFactory | undefined): HelpTheme;
81
- /** Resolve literal or function-form help description text. @internal */
82
- declare function resolveHelpDescription(description: HelpDescription, theme: HelpTheme): string;
83
- /** Resolve a help description with identity formatters for non-TTY output. @internal */
84
- declare function resolvePlainHelpDescription(description: HelpDescription): string;
85
- //#endregion
86
- export { type HelpDescription, type HelpTheme, type HelpThemeFactory, defaultHelpTheme, extendHelpTheme, resolveHelpDescription, resolveHelpTheme, resolvePlainHelpDescription };
@@ -1,69 +0,0 @@
1
- import { createColors } from "ansispeck";
2
- //#region src/core/help/theme.ts
3
- /**
4
- * The built-in help theme (clap/cargo conventions).
5
- *
6
- * @param c - Palette to build formatters from (typically the gated `out.color`).
7
- * @internal
8
- */
9
- function defaultHelpTheme(c) {
10
- return {
11
- sectionTitle: (input) => c.bold(c.underline(input)),
12
- usageBin: c.bold,
13
- flag: c.cyan,
14
- placeholder: c.dim,
15
- command: c.cyan,
16
- arg: c.cyan,
17
- defaultValue: c.dim,
18
- annotation: c.dim,
19
- deprecated: c.yellow,
20
- headerName: c.bold,
21
- headerVersion: c.dim,
22
- examplePrompt: c.dim
23
- };
24
- }
25
- /**
26
- * Resolve the effective help theme from a palette and optional user factory.
27
- *
28
- * When the palette renders no styling (color disabled — its formatters are
29
- * identity functions), the user factory is **never invoked**: even a factory
30
- * that emits raw escapes cannot leak them into color-off output. When color
31
- * is enabled, factory overrides merge over {@linkcode defaultHelpTheme}.
32
- *
33
- * @param colors - Gated palette, or `undefined` for a color-off theme.
34
- * @param theme - Optional user overrides factory.
35
- * @internal
36
- */
37
- function resolveHelpTheme(colors, theme) {
38
- const palette = colors ?? createColors(false);
39
- if (!(palette.bold("x") !== "x") || theme === void 0) return defaultHelpTheme(palette);
40
- return {
41
- ...defaultHelpTheme(palette),
42
- ...theme(palette)
43
- };
44
- }
45
- /**
46
- * Merge a scoped theme factory over an already-resolved help theme.
47
- *
48
- * The scoped factory follows the same color gate as the global factory and is
49
- * never invoked when the palette is disabled.
50
- *
51
- * @internal
52
- */
53
- function extendHelpTheme(theme, colors, override) {
54
- const palette = colors ?? createColors(false);
55
- return palette.bold("x") !== "x" && override !== void 0 ? {
56
- ...theme,
57
- ...override(palette)
58
- } : theme;
59
- }
60
- /** Resolve literal or function-form help description text. @internal */
61
- function resolveHelpDescription(description, theme) {
62
- return typeof description === "function" ? description(theme) : description;
63
- }
64
- /** Resolve a help description with identity formatters for non-TTY output. @internal */
65
- function resolvePlainHelpDescription(description) {
66
- return resolveHelpDescription(description, defaultHelpTheme(createColors(false)));
67
- }
68
- //#endregion
69
- export { defaultHelpTheme, extendHelpTheme, resolveHelpDescription, resolveHelpTheme, resolvePlainHelpDescription };