@kjanat/dreamcli 2.5.0 → 3.0.0-rc.10

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 (202) hide show
  1. package/CHANGELOG.md +344 -1
  2. package/README.md +9 -2
  3. package/dist/core/cli/dispatch.d.mts +6 -5
  4. package/dist/core/cli/dispatch.mjs +205 -1
  5. package/dist/core/cli/help-links.d.mts +0 -1
  6. package/dist/core/cli/help-links.mjs +41 -1
  7. package/dist/core/cli/index.d.mts +185 -19
  8. package/dist/core/cli/index.mjs +945 -1
  9. package/dist/core/cli/planner.d.mts +32 -6
  10. package/dist/core/cli/planner.mjs +300 -1
  11. package/dist/core/cli/plugin.d.mts +1 -1
  12. package/dist/core/cli/plugin.mjs +41 -1
  13. package/dist/core/cli/propagate.d.mts +1 -1
  14. package/dist/core/cli/propagate.mjs +57 -1
  15. package/dist/core/cli/root-help.d.mts +18 -3
  16. package/dist/core/cli/root-help.mjs +226 -6
  17. package/dist/core/cli/root-surface.d.mts +30 -4
  18. package/dist/core/cli/root-surface.mjs +28 -1
  19. package/dist/core/cli/runtime-preflight.d.mts +30 -3
  20. package/dist/core/cli/runtime-preflight.mjs +169 -1
  21. package/dist/core/completion/index.d.mts +32 -2
  22. package/dist/core/completion/index.mjs +90 -1
  23. package/dist/core/completion/shells/bash.d.mts +0 -1
  24. package/dist/core/completion/shells/bash.mjs +308 -3
  25. package/dist/core/completion/shells/fish.d.mts +0 -1
  26. package/dist/core/completion/shells/fish.mjs +162 -2
  27. package/dist/core/completion/shells/powershell.d.mts +0 -1
  28. package/dist/core/completion/shells/powershell.mjs +358 -2
  29. package/dist/core/completion/shells/shared.d.mts +23 -2
  30. package/dist/core/completion/shells/shared.mjs +176 -1
  31. package/dist/core/completion/shells/zsh.d.mts +0 -1
  32. package/dist/core/completion/shells/zsh.mjs +251 -2
  33. package/dist/core/config/index.d.mts +2 -3
  34. package/dist/core/config/index.mjs +246 -1
  35. package/dist/core/config/package-json.d.mts +27 -4
  36. package/dist/core/config/package-json.mjs +386 -3
  37. package/dist/core/errors/index.d.mts +3 -3
  38. package/dist/core/errors/index.mjs +87 -1
  39. package/dist/core/execution/index.d.mts +0 -1
  40. package/dist/core/execution/index.mjs +201 -1
  41. package/dist/core/help/ansi.d.mts +11 -5
  42. package/dist/core/help/ansi.mjs +121 -2
  43. package/dist/core/help/index.d.mts +65 -2
  44. package/dist/core/help/index.mjs +341 -7
  45. package/dist/core/help/theme.d.mts +68 -0
  46. package/dist/core/help/theme.mjs +46 -0
  47. package/dist/core/json-schema/index.d.mts +15 -2
  48. package/dist/core/json-schema/index.mjs +536 -12
  49. package/dist/core/json-schema/meta-descriptions.generated.d.mts +22 -5
  50. package/dist/core/json-schema/meta-descriptions.generated.mjs +102 -28
  51. package/dist/core/output/activity.d.mts +0 -1
  52. package/dist/core/output/activity.mjs +452 -1
  53. package/dist/core/output/bind.mjs +56 -1
  54. package/dist/core/output/contracts.d.mts +4 -5
  55. package/dist/core/output/contracts.mjs +57 -1
  56. package/dist/core/output/display-value.mjs +32 -1
  57. package/dist/core/output/index.d.mts +21 -1
  58. package/dist/core/output/index.mjs +442 -2
  59. package/dist/core/output/renderers.d.mts +0 -1
  60. package/dist/core/output/renderers.mjs +46 -1
  61. package/dist/core/output/writer.mjs +12 -1
  62. package/dist/core/parse/index.d.mts +54 -7
  63. package/dist/core/parse/index.mjs +727 -1
  64. package/dist/core/prompt/index.d.mts +12 -4
  65. package/dist/core/prompt/index.mjs +348 -6
  66. package/dist/core/resolve/args.d.mts +1 -1
  67. package/dist/core/resolve/args.mjs +105 -1
  68. package/dist/core/resolve/coerce.d.mts +1 -1
  69. package/dist/core/resolve/coerce.mjs +336 -1
  70. package/dist/core/resolve/config.mjs +19 -1
  71. package/dist/core/resolve/contracts.d.mts +9 -4
  72. package/dist/core/resolve/errors.d.mts +0 -1
  73. package/dist/core/resolve/errors.mjs +140 -2
  74. package/dist/core/resolve/flags.d.mts +7 -2
  75. package/dist/core/resolve/flags.mjs +251 -1
  76. package/dist/core/resolve/index.d.mts +2 -2
  77. package/dist/core/resolve/index.mjs +85 -1
  78. package/dist/core/resolve/property.d.mts +6 -2
  79. package/dist/core/resolve/property.mjs +53 -1
  80. package/dist/core/schema/activity.d.mts +31 -11
  81. package/dist/core/schema/arg.d.mts +92 -13
  82. package/dist/core/schema/arg.mjs +463 -1
  83. package/dist/core/schema/command.d.mts +29 -7
  84. package/dist/core/schema/command.mjs +726 -1
  85. package/dist/core/schema/flag.d.mts +577 -21
  86. package/dist/core/schema/flag.mjs +705 -1
  87. package/dist/core/schema/index.d.mts +5 -2
  88. package/dist/core/schema/middleware.d.mts +4 -3
  89. package/dist/core/schema/middleware.mjs +41 -1
  90. package/dist/core/schema/number-constraints.d.mts +96 -0
  91. package/dist/core/schema/number-constraints.mjs +60 -0
  92. package/dist/core/schema/prompt.d.mts +21 -3
  93. package/dist/core/schema/run.d.mts +24 -5
  94. package/dist/core/schema/string-constraints.d.mts +97 -0
  95. package/dist/core/schema/string-constraints.mjs +69 -0
  96. package/dist/core/schema/value-parsers.d.mts +78 -0
  97. package/dist/core/schema/value-parsers.mjs +142 -0
  98. package/dist/core/schema-dsl/runtime.mjs +271 -2
  99. package/dist/core/schema-dsl/to-json-schema.d.mts +0 -1
  100. package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
  101. package/dist/core/testkit/index.d.mts +9 -36
  102. package/dist/core/testkit/index.mjs +83 -1
  103. package/dist/index.d.mts +12 -6
  104. package/dist/index.mjs +22 -1
  105. package/dist/runtime/adapter.d.mts +38 -2
  106. package/dist/runtime/adapter.mjs +87 -1
  107. package/dist/runtime/auto.d.mts +2 -3
  108. package/dist/runtime/auto.mjs +45 -1
  109. package/dist/runtime/deno.d.mts +24 -5
  110. package/dist/runtime/deno.mjs +262 -2
  111. package/dist/runtime/detect.mjs +45 -1
  112. package/dist/runtime/index.d.mts +3 -4
  113. package/dist/runtime/node.d.mts +8 -2
  114. package/dist/runtime/node.mjs +220 -2
  115. package/dist/runtime/paths.mjs +48 -1
  116. package/dist/runtime.d.mts +4 -4
  117. package/dist/runtime.mjs +6 -1
  118. package/dist/strings.mjs +22 -1
  119. package/dist/testkit.d.mts +1 -0
  120. package/dist/testkit.mjs +5 -1
  121. package/dist/version.d.mts +7 -3
  122. package/dist/version.mjs +7 -1
  123. package/dreamcli.schema.json +36 -7
  124. package/examples/basic.ts +5 -1
  125. package/examples/gh/package.json +2 -7
  126. package/examples/pwsh-demo/package.json +1 -7
  127. package/examples/pwsh-demo/src/main.test.ts +1 -4
  128. package/examples/pwsh-demo/src/main.ts +14 -4
  129. package/examples/transport-launcher.ts +85 -0
  130. package/package.json +43 -49
  131. package/dist/runtime/bun.d.mts +0 -28
  132. package/dist/runtime/bun.mjs +0 -1
  133. package/dist/runtime/support.d.mts +0 -42
  134. package/dist/runtime/support.mjs +0 -1
  135. package/src/core/cli/dispatch.ts +0 -349
  136. package/src/core/cli/help-links.ts +0 -82
  137. package/src/core/cli/index.ts +0 -1413
  138. package/src/core/cli/planner.ts +0 -487
  139. package/src/core/cli/plugin.ts +0 -117
  140. package/src/core/cli/propagate.ts +0 -97
  141. package/src/core/cli/root-help.ts +0 -252
  142. package/src/core/cli/root-surface.ts +0 -74
  143. package/src/core/cli/runtime-preflight.ts +0 -438
  144. package/src/core/completion/index.ts +0 -88
  145. package/src/core/completion/shells/bash.ts +0 -459
  146. package/src/core/completion/shells/fish.ts +0 -259
  147. package/src/core/completion/shells/powershell.ts +0 -439
  148. package/src/core/completion/shells/shared.ts +0 -283
  149. package/src/core/completion/shells/zsh.ts +0 -381
  150. package/src/core/config/index.ts +0 -417
  151. package/src/core/config/package-json.ts +0 -560
  152. package/src/core/errors/index.ts +0 -193
  153. package/src/core/execution/index.ts +0 -268
  154. package/src/core/help/ansi.ts +0 -144
  155. package/src/core/help/index.ts +0 -516
  156. package/src/core/json-schema/index.ts +0 -891
  157. package/src/core/json-schema/meta-descriptions.generated.ts +0 -185
  158. package/src/core/output/activity.ts +0 -575
  159. package/src/core/output/bind.ts +0 -59
  160. package/src/core/output/contracts.ts +0 -194
  161. package/src/core/output/display-value.ts +0 -48
  162. package/src/core/output/index.ts +0 -704
  163. package/src/core/output/renderers.ts +0 -125
  164. package/src/core/output/writer.ts +0 -46
  165. package/src/core/parse/index.ts +0 -681
  166. package/src/core/prompt/index.ts +0 -583
  167. package/src/core/resolve/args.ts +0 -144
  168. package/src/core/resolve/coerce.ts +0 -432
  169. package/src/core/resolve/config.ts +0 -26
  170. package/src/core/resolve/contracts.ts +0 -135
  171. package/src/core/resolve/errors.ts +0 -227
  172. package/src/core/resolve/flags.ts +0 -255
  173. package/src/core/resolve/index.ts +0 -108
  174. package/src/core/resolve/property.ts +0 -99
  175. package/src/core/schema/activity.ts +0 -240
  176. package/src/core/schema/arg.ts +0 -719
  177. package/src/core/schema/command.ts +0 -1498
  178. package/src/core/schema/flag.ts +0 -801
  179. package/src/core/schema/index.ts +0 -91
  180. package/src/core/schema/middleware.ts +0 -171
  181. package/src/core/schema/prompt.ts +0 -156
  182. package/src/core/schema/run.ts +0 -198
  183. package/src/core/schema-dsl/index.ts +0 -109
  184. package/src/core/schema-dsl/parse.ts +0 -262
  185. package/src/core/schema-dsl/runtime.ts +0 -609
  186. package/src/core/schema-dsl/to-json-schema.ts +0 -102
  187. package/src/core/testkit/index.ts +0 -123
  188. package/src/index.ts +0 -179
  189. package/src/runtime/adapter.ts +0 -303
  190. package/src/runtime/auto.ts +0 -110
  191. package/src/runtime/bun.ts +0 -55
  192. package/src/runtime/deno.ts +0 -369
  193. package/src/runtime/detect.ts +0 -105
  194. package/src/runtime/index.ts +0 -21
  195. package/src/runtime/node-builtins.d.ts +0 -27
  196. package/src/runtime/node.ts +0 -300
  197. package/src/runtime/paths.ts +0 -64
  198. package/src/runtime/support.ts +0 -135
  199. package/src/runtime.ts +0 -31
  200. package/src/strings.ts +0 -34
  201. package/src/testkit.ts +0 -25
  202. package/src/version.ts +0 -20
@@ -1,7 +1,341 @@
1
- import{getFlagAliasNames as e}from"../schema/flag.mjs";import{formatDisplayValue as t}from"../output/display-value.mjs";import{padEnd as n,wrapText as r}from"./ansi.mjs";function i(e){return{width:e?.width??80,binName:e?.binName,isDefaultHelp:e?.isDefaultHelp??!1}}function a(e){return typeof e==`string`?`[deprecated: ${e}]`:`[deprecated]`}function o(e){return e===void 0?`undefined`:e===null?`null`:t(e)}function s(t,n){let r=e(n,{kind:`short`}),i=e(n,{kind:`long`}),a=[...r.map(e=>`-${e}`),`--${t}`,...i.map(e=>`--${e}`)];return n.kind===`boolean`?a.join(`, `):`${a.join(`, `)} ${c(n)}`}function c(e){switch(e.kind){case`string`:return`<string>`;case`number`:return`<number>`;case`enum`:return`<${(e.enumValues??[]).join(`|`)}>`;case`array`:return`<${e.elementSchema===void 0?`value`:c(e.elementSchema).slice(1,-1)}>...`;case`boolean`:return``;case`custom`:return`<value>`}}function l(e){let t=[];return e.description!==void 0&&t.push(e.description),e.deprecated!==void 0&&t.push(a(e.deprecated)),e.envVar!==void 0&&t.push(`[env: ${e.envVar}]`),e.configPath!==void 0&&t.push(`[config: ${e.configPath}]`),e.prompt!==void 0&&t.push(`[prompt]`),e.presence===`required`?t.push(`[required]`):e.presence===`defaulted`&&e.kind!==`boolean`&&t.push(`(default: ${o(e.defaultValue)})`),t.join(` `)}function u(t){let n=Object.keys(t);if(n.length===0)return[];let r=[...n].sort((n,r)=>{let i=t[n],a=t[r];if(i===void 0||a===void 0)return 0;let o=e(i,{kind:`short`}).length>0,s=e(a,{kind:`short`}).length>0;return o&&!s?-1:!o&&s?1:n.localeCompare(r)}),i=[];for(let e of r){let n=t[e];n!==void 0&&i.push({left:s(e,n),description:l(n)})}return i}function d(e){let{name:t,schema:n}=e,r=n.kind===`enum`&&n.enumValues!==void 0?n.enumValues.join(`|`):t,i=n.variadic?`...`:``;return n.presence===`required`?`<${r}>${i}`:`[${r}]${i}`}function f(e){let t=[];return e.description!==void 0&&t.push(e.description),e.deprecated!==void 0&&t.push(a(e.deprecated)),e.envVar!==void 0&&t.push(`[env: ${e.envVar}]`),e.presence===`defaulted`&&t.push(`(default: ${o(e.defaultValue)})`),t.join(` `)}function p(e,t){let n=i(t),r=[];r.push(h(e,n)),e.description!==void 0&&r.push(e.description);let a=e.commands.filter(e=>!e.hidden);return a.length>0&&r.push(v(a,n)),e.args.length>0&&r.push(g(e.args,n)),Object.keys(e.flags).length>0&&r.push(_(e.flags,n)),e.examples.length>0&&r.push(y(e.examples)),r}function m(e,t){return`${p(e,t).join(`
2
-
3
- `)}\n`}function h(e,t){let n=[`Usage:`],r=t.binName===void 0||t.isDefaultHelp&&t.binName===e.name?e.name:`${t.binName} ${e.name}`;n.push(r),e.commands.length>0&&n.push(`<command>`),Object.keys(e.flags).length>0&&n.push(`[flags]`);for(let t of e.args)n.push(d(t));return n.join(` `)}function g(e,t){let i=[`Arguments:`],a=0,o=[];for(let t of e){let e=` ${d(t)}`,n=f(t.schema);o.push({left:e,desc:n}),e.length>a&&(a=e.length)}let s=a+2;for(let{left:e,desc:a}of o)if(a.length===0)i.push(e);else{let o=n(e,s),c=r(a,t.width,s);i.push(`${o}${c}`)}return i.join(`
4
- `)}function _(e,t){let i=[`Flags:`],a=u(e);if(a.length===0)return``;let o=0;for(let e of a){let t=` ${e.left}`;t.length>o&&(o=t.length)}let s=o+2;for(let e of a){let a=` ${e.left}`;if(e.description.length===0)i.push(a);else{let o=n(a,s),c=r(e.description,t.width,s);i.push(`${o}${c}`)}}return i.join(`
5
- `)}function v(e,t){let i=[`Commands:`],a=0;for(let t of e)t.name.length>a&&(a=t.name.length);let o=2+a+2;for(let a of e){let e=` ${a.name}`,s=a.description??``;if(s.length===0)i.push(e);else{let a=n(e,o),c=r(s,t.width,o);i.push(`${a}${c}`)}}return i.join(`
6
- `)}function y(e){let t=[`Examples:`];for(let n of e)n.description===void 0?t.push(` $ ${n.command}`):(t.push(` ${n.description}:`),t.push(` $ ${n.command}`));return t.join(`
7
- `)}export{m as formatHelp,p as formatHelpSections};
1
+ import { getFlagAliasNames } from "../schema/flag.mjs";
2
+ import { formatDisplayValue } from "../output/display-value.mjs";
3
+ import { osc8, padEnd, visibleWidth, wrapText } from "./ansi.mjs";
4
+ import { resolveHelpTheme } from "./theme.mjs";
5
+ //#region src/core/help/index.ts
6
+ const DEFAULT_WIDTH = 80;
7
+ /**
8
+ * Apply defaults to optional {@link HelpOptions}.
9
+ *
10
+ * @param options - User-supplied help options, or `undefined` for all defaults.
11
+ * @returns Fully resolved options with defaults applied.
12
+ */
13
+ function resolveOptions(options) {
14
+ return {
15
+ width: options?.width ?? DEFAULT_WIDTH,
16
+ binName: options?.binName,
17
+ isDefaultHelp: options?.isDefaultHelp ?? false,
18
+ theme: resolveHelpTheme(options?.colors, options?.theme)
19
+ };
20
+ }
21
+ /**
22
+ * Format a deprecation annotation for help text.
23
+ *
24
+ * @param deprecated - `true` for a generic marker, or a string explaining the deprecation.
25
+ * @returns Bracketed deprecation label, e.g. `[deprecated]` or `[deprecated: use --foo]`.
26
+ */
27
+ function formatDeprecated(deprecated) {
28
+ return typeof deprecated === "string" ? `[deprecated: ${deprecated}]` : "[deprecated]";
29
+ }
30
+ /** Format a default value for help output, preserving nullish sentinels. */
31
+ function formatHelpDefaultValue(value) {
32
+ if (value === void 0) return "undefined";
33
+ if (value === null) return "null";
34
+ return formatDisplayValue(value);
35
+ }
36
+ /**
37
+ * Format a flag's left column: `-a, --name <type>`.
38
+ *
39
+ * @param name - Long flag name (without `--` prefix).
40
+ * @param schema - The {@link FlagSchema} describing the flag.
41
+ * @param theme - Theme applied to the flag forms and value hint.
42
+ * @returns Formatted left-column string for the flags table.
43
+ */
44
+ function formatFlagLeft(name, schema, theme) {
45
+ const visibleShortAliases = getFlagAliasNames(schema, { kind: "short" });
46
+ const visibleLongAliases = getFlagAliasNames(schema, { kind: "long" });
47
+ const negation = schema.negation !== void 0 && !schema.negation.hidden ? schema.negation : void 0;
48
+ const canonicalForm = negation !== void 0 && negation.alias === void 0 ? `--[no-]${name}` : `--${name}`;
49
+ const forms = [
50
+ ...visibleShortAliases.map((alias) => `-${alias}`),
51
+ canonicalForm,
52
+ ...visibleLongAliases.map((alias) => `--${alias}`),
53
+ ...negation?.alias !== void 0 ? [`--${negation.alias}`] : []
54
+ ];
55
+ if (schema.kind !== "boolean" && schema.kind !== "count") return `${theme.flag(forms.join(", "))} ${theme.placeholder(formatValueHint(schema))}`;
56
+ return theme.flag(forms.join(", "));
57
+ }
58
+ /**
59
+ * Produce a type hint like `<string>`, `<number>`, `<us|eu|ap>`.
60
+ *
61
+ * A schema-level `valueHint` (set by sugar factories like `flag.url()`)
62
+ * overrides the kind-derived hint.
63
+ *
64
+ * @param schema - The {@link FlagSchema} whose value type determines the hint.
65
+ * @returns Angle-bracketed hint string, or empty string for no-value kinds.
66
+ */
67
+ function formatValueHint(schema) {
68
+ if (schema.valueHint !== void 0) return `<${schema.valueHint}>`;
69
+ switch (schema.kind) {
70
+ case "string": return "<string>";
71
+ case "number": return "<number>";
72
+ case "enum": return `<${(schema.enumValues ?? []).join("|")}>`;
73
+ case "array": return `<${schema.elementSchema !== void 0 ? formatValueHint(schema.elementSchema).slice(1, -1) : "value"}>...`;
74
+ case "boolean":
75
+ case "count": return "";
76
+ case "custom": return "<value>";
77
+ case "keyValue": return "<key=value>";
78
+ }
79
+ }
80
+ /**
81
+ * Build description with env/config/prompt/default/required/deprecated annotations.
82
+ *
83
+ * @param schema - The {@link FlagSchema} to describe.
84
+ * @param theme - Theme applied to the metadata annotations (description stays plain).
85
+ * @returns Concatenated description string with metadata annotations.
86
+ */
87
+ function formatFlagDescription(schema, theme) {
88
+ const parts = [];
89
+ if (schema.description !== void 0) parts.push(schema.description);
90
+ if (schema.deprecated !== void 0) parts.push(theme.deprecated(formatDeprecated(schema.deprecated)));
91
+ if (schema.envVar !== void 0) parts.push(theme.annotation(`[env: ${schema.envVar}]`));
92
+ if (schema.configPath !== void 0) parts.push(theme.annotation(`[config: ${schema.configPath}]`));
93
+ if (schema.prompt !== void 0) parts.push(theme.annotation("[prompt]"));
94
+ if (schema.presence === "required") parts.push(theme.annotation("[required]"));
95
+ else if (schema.presence === "defaulted" && schema.kind !== "boolean" && schema.kind !== "count") parts.push(theme.defaultValue(`(default: ${formatHelpDefaultValue(schema.defaultValue)})`));
96
+ return parts.join(" ");
97
+ }
98
+ /**
99
+ * Build the flag entries sorted: short-aliased first, then alphabetical.
100
+ *
101
+ * @param flags - Map of flag names to {@link FlagSchema} definitions.
102
+ * @param theme - Theme threaded into the per-flag formatters.
103
+ * @returns Sorted array of {@link FlagEntry} objects for the flags table.
104
+ */
105
+ function buildFlagEntries(flags, theme) {
106
+ const names = Object.keys(flags);
107
+ if (names.length === 0) return [];
108
+ const sorted = [...names].sort((a, b) => {
109
+ const aSchema = flags[a];
110
+ const bSchema = flags[b];
111
+ if (aSchema === void 0 || bSchema === void 0) return 0;
112
+ const aHasShort = getFlagAliasNames(aSchema, { kind: "short" }).length > 0;
113
+ const bHasShort = getFlagAliasNames(bSchema, { kind: "short" }).length > 0;
114
+ if (aHasShort && !bHasShort) return -1;
115
+ if (!aHasShort && bHasShort) return 1;
116
+ return a.localeCompare(b);
117
+ });
118
+ const entries = [];
119
+ for (const name of sorted) {
120
+ const schema = flags[name];
121
+ if (schema === void 0) continue;
122
+ entries.push({
123
+ left: formatFlagLeft(name, schema, theme),
124
+ description: formatFlagDescription(schema, theme)
125
+ });
126
+ }
127
+ return entries;
128
+ }
129
+ /**
130
+ * Format a positional arg for the usage line.
131
+ *
132
+ * @param entry - The {@link CommandArgEntry} containing name and schema.
133
+ * @returns Bracketed arg token, e.g. `<file>` or `[output]...`.
134
+ */
135
+ function formatArgUsage(entry) {
136
+ const { name, schema } = entry;
137
+ const label = schema.kind === "enum" && schema.enumValues !== void 0 ? schema.enumValues.join("|") : name;
138
+ const variadicSuffix = schema.variadic ? "..." : "";
139
+ if (schema.presence === "required") return `<${label}>${variadicSuffix}`;
140
+ return `[${label}]${variadicSuffix}`;
141
+ }
142
+ /**
143
+ * Format arg description with annotations.
144
+ *
145
+ * @param schema - The {@link ArgSchema} to describe.
146
+ * @param theme - Theme applied to the metadata annotations (description stays plain).
147
+ * @returns Concatenated description string with metadata annotations.
148
+ */
149
+ function formatArgDescription(schema, theme) {
150
+ const parts = [];
151
+ if (schema.description !== void 0) parts.push(schema.description);
152
+ if (schema.deprecated !== void 0) parts.push(theme.deprecated(formatDeprecated(schema.deprecated)));
153
+ if (schema.envVar !== void 0) parts.push(theme.annotation(`[env: ${schema.envVar}]`));
154
+ if (schema.presence === "defaulted") parts.push(theme.defaultValue(`(default: ${formatHelpDefaultValue(schema.defaultValue)})`));
155
+ return parts.join(" ");
156
+ }
157
+ /**
158
+ * Build the ordered help sections without joining them.
159
+ *
160
+ * @internal
161
+ * @param schema - The {@link CommandSchema} to render.
162
+ * @param options - Optional {@link HelpOptions} for width/bin name.
163
+ * @returns Array of section strings (usage, description, commands, args, flags, examples).
164
+ */
165
+ function formatHelpSections(schema, options) {
166
+ const opts = resolveOptions(options);
167
+ const sections = [];
168
+ sections.push(formatUsageLine(schema, opts));
169
+ if (schema.description !== void 0) sections.push(schema.description);
170
+ const visibleCommands = schema.commands.filter((c) => !c.hidden);
171
+ if (visibleCommands.length > 0) sections.push(formatCommandsSection(visibleCommands, opts));
172
+ if (schema.args.length > 0) sections.push(formatArgsSection(schema.args, opts));
173
+ if (Object.keys(schema.flags).length > 0) sections.push(formatFlagsSection(schema.flags, opts));
174
+ if (schema.examples.length > 0) sections.push(formatExamplesSection(schema.examples, opts.theme));
175
+ return sections;
176
+ }
177
+ /**
178
+ * Generate help text from a command schema.
179
+ *
180
+ * Low-level formatter: most applications reach this through `--help`,
181
+ * `help <command>`, or root help rendering in `CLIBuilder`. Call
182
+ * `formatHelp()` directly when embedding DreamCLI help text into custom UIs,
183
+ * tests, or generated docs.
184
+ *
185
+ * Sections rendered (in order):
186
+ * 1. **Usage** line — `program <command> [flags] <args>`
187
+ * 2. **Description** — the command's `.description()` text
188
+ * 3. **Commands** — subcommands table (if any, skips hidden)
189
+ * 4. **Arguments** — positional args table (if any)
190
+ * 5. **Flags** — flags table with type hints and defaults
191
+ * 6. **Examples** — usage examples (if any)
192
+ *
193
+ * @param schema - The command schema to render help for.
194
+ * @param options - Formatting options (width, binary name).
195
+ * @returns The formatted help string.
196
+ *
197
+ * @example
198
+ * ```ts
199
+ * const text = formatHelp(deploy.schema, { binName: 'mycli' });
200
+ * ```
201
+ */
202
+ function formatHelp(schema, options) {
203
+ return `${formatHelpSections(schema, options).join("\n\n")}\n`;
204
+ }
205
+ /**
206
+ * Render the `Usage:` line for a command.
207
+ *
208
+ * @param schema - The {@link CommandSchema} to summarize.
209
+ * @param opts - Resolved help options (bin name, default-help flag).
210
+ * @returns Single-line usage string, e.g. `Usage: mycli deploy [flags] <env>`.
211
+ */
212
+ function formatUsageLine(schema, opts) {
213
+ const { theme } = opts;
214
+ const parts = [theme.sectionTitle("Usage:")];
215
+ const cmdName = opts.binName === void 0 ? schema.name : opts.isDefaultHelp ? opts.binName : `${opts.binName} ${schema.name}`;
216
+ parts.push(theme.usageBin(cmdName));
217
+ if (schema.commands.length > 0) parts.push(theme.placeholder("<command>"));
218
+ if (Object.keys(schema.flags).length > 0) parts.push(theme.placeholder("[flags]"));
219
+ for (const entry of schema.args) parts.push(theme.arg(formatArgUsage(entry)));
220
+ return parts.join(" ");
221
+ }
222
+ /**
223
+ * Render the `Arguments:` help section.
224
+ *
225
+ * @param args - Positional arg entries from the {@link CommandSchema}.
226
+ * @param opts - Resolved help options for line-width wrapping.
227
+ * @returns Multi-line arguments section string.
228
+ */
229
+ function formatArgsSection(args, opts) {
230
+ const { theme } = opts;
231
+ const lines = [theme.sectionTitle("Arguments:")];
232
+ const GAP = 2;
233
+ let maxLeft = 0;
234
+ const entries = [];
235
+ for (const entry of args) {
236
+ const left = ` ${theme.arg(formatArgUsage(entry))}`;
237
+ const desc = formatArgDescription(entry.schema, theme);
238
+ entries.push({
239
+ left,
240
+ desc
241
+ });
242
+ const leftWidth = visibleWidth(left);
243
+ if (leftWidth > maxLeft) maxLeft = leftWidth;
244
+ }
245
+ const descCol = maxLeft + GAP;
246
+ for (const { left, desc } of entries) if (desc.length === 0) lines.push(left);
247
+ else {
248
+ const padded = padEnd(left, descCol);
249
+ const wrapped = wrapText(desc, opts.width, descCol);
250
+ lines.push(`${padded}${wrapped}`);
251
+ }
252
+ return lines.join("\n");
253
+ }
254
+ /**
255
+ * Render the `Flags:` help section.
256
+ *
257
+ * @param flags - Map of flag names to {@link FlagSchema} definitions.
258
+ * @param opts - Resolved help options for line-width wrapping.
259
+ * @returns Multi-line flags section string.
260
+ */
261
+ function formatFlagsSection(flags, opts) {
262
+ return formatFlagEntriesBlock(opts.theme.sectionTitle("Flags:"), buildFlagEntries(flags, opts.theme), opts.width);
263
+ }
264
+ /**
265
+ * Render a titled two-column flag block from pre-built {@link FlagEntry} rows.
266
+ *
267
+ * Shared by the per-command `Flags:` section and the root-help `Global options:`
268
+ * block (built-in flags), so column alignment and description wrapping stay
269
+ * identical across both. Returns `''` when there are no entries.
270
+ *
271
+ * @param title - Section heading (e.g. `'Flags:'`, `'Global options:'`), pre-styled by the caller.
272
+ * @param entries - Formatted left/description rows.
273
+ * @param width - Terminal width for description wrapping.
274
+ * @returns Multi-line block string, or `''` when `entries` is empty.
275
+ * @internal
276
+ */
277
+ function formatFlagEntriesBlock(title, entries, width) {
278
+ if (entries.length === 0) return "";
279
+ const lines = [title];
280
+ const GAP = 2;
281
+ let maxLeft = 0;
282
+ for (const entry of entries) {
283
+ const indentedWidth = visibleWidth(entry.left) + 2;
284
+ if (indentedWidth > maxLeft) maxLeft = indentedWidth;
285
+ }
286
+ const descCol = maxLeft + GAP;
287
+ for (const entry of entries) {
288
+ const left = ` ${entry.left}`;
289
+ if (entry.description.length === 0) lines.push(left);
290
+ else {
291
+ const padded = padEnd(left, descCol);
292
+ const wrapped = wrapText(entry.description, width, descCol);
293
+ lines.push(`${padded}${wrapped}`);
294
+ }
295
+ }
296
+ return lines.join("\n");
297
+ }
298
+ /**
299
+ * Render the `Commands:` help section.
300
+ *
301
+ * @param commands - Visible subcommand schemas (hidden commands pre-filtered).
302
+ * @param opts - Resolved help options for line-width wrapping.
303
+ * @returns Multi-line commands section string.
304
+ */
305
+ function formatCommandsSection(commands, opts) {
306
+ const { theme } = opts;
307
+ const lines = [theme.sectionTitle("Commands:")];
308
+ const GAP = 2;
309
+ let maxNameLen = 0;
310
+ for (const cmd of commands) if (cmd.name.length > maxNameLen) maxNameLen = cmd.name.length;
311
+ const descCol = 2 + maxNameLen + GAP;
312
+ for (const cmd of commands) {
313
+ const left = ` ${theme.command(cmd.name)}`;
314
+ const desc = cmd.description ?? "";
315
+ if (desc.length === 0) lines.push(left);
316
+ else {
317
+ const padded = padEnd(left, descCol);
318
+ const wrapped = wrapText(desc, opts.width, descCol);
319
+ lines.push(`${padded}${wrapped}`);
320
+ }
321
+ }
322
+ return lines.join("\n");
323
+ }
324
+ /**
325
+ * Render the `Examples:` help section.
326
+ *
327
+ * @param examples - Array of {@link CommandExample} entries.
328
+ * @param theme - Theme applied to the section title and `$` prompt marker.
329
+ * @returns Multi-line examples section string.
330
+ */
331
+ function formatExamplesSection(examples, theme) {
332
+ const lines = [theme.sectionTitle("Examples:")];
333
+ const prompt = theme.examplePrompt("$");
334
+ for (const example of examples) if (example.description !== void 0) {
335
+ lines.push(` ${example.description}:`);
336
+ lines.push(` ${prompt} ${example.command}`);
337
+ } else lines.push(` ${prompt} ${example.command}`);
338
+ return lines.join("\n");
339
+ }
340
+ //#endregion
341
+ export { formatFlagEntriesBlock, formatHelp, formatHelpSections, osc8, visibleWidth };
@@ -0,0 +1,68 @@
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
+ * User theme customization: receives the gated palette and returns role
40
+ * overrides merged over the default theme.
41
+ *
42
+ * The palette formatters are identity functions when color is disabled, and
43
+ * the factory itself is only invoked when color is enabled — style
44
+ * unconditionally, gating is the framework's job.
45
+ */
46
+ type HelpThemeFactory = (colors: Colors) => Partial<HelpTheme>;
47
+ /**
48
+ * The built-in help theme (clap/cargo conventions).
49
+ *
50
+ * @param c - Palette to build formatters from (typically the gated `out.color`).
51
+ * @internal
52
+ */
53
+ declare function defaultHelpTheme(c: Colors): HelpTheme;
54
+ /**
55
+ * Resolve the effective help theme from a palette and optional user factory.
56
+ *
57
+ * When the palette renders no styling (color disabled — its formatters are
58
+ * identity functions), the user factory is **never invoked**: even a factory
59
+ * that emits raw escapes cannot leak them into color-off output. When color
60
+ * is enabled, factory overrides merge over {@linkcode defaultHelpTheme}.
61
+ *
62
+ * @param colors - Gated palette, or `undefined` for a color-off theme.
63
+ * @param theme - Optional user overrides factory.
64
+ * @internal
65
+ */
66
+ declare function resolveHelpTheme(colors: Colors | undefined, theme: HelpThemeFactory | undefined): HelpTheme;
67
+ //#endregion
68
+ export { type HelpTheme, type HelpThemeFactory, defaultHelpTheme, resolveHelpTheme };
@@ -0,0 +1,46 @@
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
+ //#endregion
46
+ export { defaultHelpTheme, resolveHelpTheme };
@@ -1,6 +1,6 @@
1
1
  import { CommandSchema } from "../schema/command.mjs";
2
+ import "../schema/index.mjs";
2
3
  import { CLISchema } from "../cli/index.mjs";
3
-
4
4
  //#region src/core/json-schema/index.d.ts
5
5
  /**
6
6
  * Options for JSON Schema generation.
@@ -53,6 +53,19 @@ interface JsonSchemaOptions {
53
53
  * ```
54
54
  */
55
55
  declare function generateSchema(schema: CLISchema, options?: JsonSchemaOptions): Record<string, unknown>;
56
+ /**
57
+ * Generate the definition metadata document for a single command.
58
+ *
59
+ * The per-command counterpart of {@link generateSchema}: the same
60
+ * JSON-serializable shape as one entry of its `commands` array (flags, args,
61
+ * subcommands, examples). Powers `--help` in `--json` mode and is useful for
62
+ * embedding one command's definition into custom tooling.
63
+ *
64
+ * @param schema - The command schema to serialize.
65
+ * @param options - Generation options.
66
+ * @returns A plain object suitable for `JSON.stringify()`.
67
+ */
68
+ declare function generateCommandSchema(schema: CommandSchema, options?: JsonSchemaOptions): Record<string, unknown>;
56
69
  /**
57
70
  * Generate a JSON Schema (draft 2020-12) for validating CLI input as JSON.
58
71
  *
@@ -106,4 +119,4 @@ declare function generateInputSchema(schema: CLISchema | CommandSchema, options?
106
119
  */
107
120
  declare const definitionMetaSchema: Record<string, unknown>;
108
121
  //#endregion
109
- export { type JsonSchemaOptions, definitionMetaSchema, generateInputSchema, generateSchema };
122
+ export { type JsonSchemaOptions, definitionMetaSchema, generateCommandSchema, generateInputSchema, generateSchema };