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

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 +37 -1
  2. package/dist/core/cli/dispatch.mjs +214 -1
  3. package/dist/core/cli/help-links.mjs +41 -1
  4. package/dist/core/cli/index.mjs +901 -1
  5. package/dist/core/cli/planner.mjs +300 -1
  6. package/dist/core/cli/plugin.mjs +41 -1
  7. package/dist/core/cli/propagate.mjs +57 -1
  8. package/dist/core/cli/root-help.mjs +208 -4
  9. package/dist/core/cli/root-surface.mjs +27 -1
  10. package/dist/core/cli/runtime-preflight.mjs +168 -1
  11. package/dist/core/completion/index.mjs +90 -1
  12. package/dist/core/completion/shells/bash.mjs +304 -3
  13. package/dist/core/completion/shells/fish.mjs +159 -2
  14. package/dist/core/completion/shells/powershell.mjs +353 -2
  15. package/dist/core/completion/shells/shared.mjs +154 -1
  16. package/dist/core/completion/shells/zsh.mjs +244 -2
  17. package/dist/core/config/index.mjs +246 -1
  18. package/dist/core/config/package-json.mjs +385 -3
  19. package/dist/core/errors/index.mjs +87 -1
  20. package/dist/core/execution/index.mjs +189 -1
  21. package/dist/core/help/ansi.mjs +122 -2
  22. package/dist/core/help/index.mjs +329 -7
  23. package/dist/core/json-schema/index.mjs +487 -9
  24. package/dist/core/json-schema/meta-descriptions.generated.mjs +93 -28
  25. package/dist/core/output/activity.mjs +452 -1
  26. package/dist/core/output/bind.mjs +56 -1
  27. package/dist/core/output/contracts.mjs +57 -1
  28. package/dist/core/output/display-value.mjs +32 -1
  29. package/dist/core/output/index.d.mts +21 -0
  30. package/dist/core/output/index.mjs +442 -2
  31. package/dist/core/output/renderers.mjs +46 -1
  32. package/dist/core/output/writer.mjs +12 -1
  33. package/dist/core/parse/index.mjs +555 -1
  34. package/dist/core/prompt/index.d.mts +0 -1
  35. package/dist/core/prompt/index.mjs +348 -6
  36. package/dist/core/resolve/args.mjs +105 -1
  37. package/dist/core/resolve/coerce.mjs +279 -1
  38. package/dist/core/resolve/config.mjs +19 -1
  39. package/dist/core/resolve/errors.mjs +140 -2
  40. package/dist/core/resolve/flags.mjs +196 -1
  41. package/dist/core/resolve/index.mjs +85 -1
  42. package/dist/core/resolve/property.d.mts +0 -1
  43. package/dist/core/resolve/property.mjs +45 -1
  44. package/dist/core/schema/arg.mjs +463 -1
  45. package/dist/core/schema/command.d.mts +18 -0
  46. package/dist/core/schema/command.mjs +712 -1
  47. package/dist/core/schema/flag.mjs +453 -1
  48. package/dist/core/schema/middleware.mjs +41 -1
  49. package/dist/core/schema/number-constraints.mjs +60 -1
  50. package/dist/core/schema-dsl/runtime.mjs +271 -2
  51. package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
  52. package/dist/core/testkit/index.mjs +83 -1
  53. package/dist/index.d.mts +2 -1
  54. package/dist/index.mjs +22 -1
  55. package/dist/runtime/adapter.mjs +82 -1
  56. package/dist/runtime/auto.mjs +46 -1
  57. package/dist/runtime/bun.mjs +28 -1
  58. package/dist/runtime/deno.mjs +217 -2
  59. package/dist/runtime/detect.mjs +45 -1
  60. package/dist/runtime/node.mjs +169 -2
  61. package/dist/runtime/paths.mjs +48 -1
  62. package/dist/runtime.mjs +7 -1
  63. package/dist/strings.mjs +22 -1
  64. package/dist/testkit.mjs +5 -1
  65. package/dist/version.d.mts +7 -3
  66. package/dist/version.mjs +7 -1
  67. package/package.json +21 -26
  68. package/src/core/cli/dispatch.ts +0 -355
  69. package/src/core/cli/help-links.ts +0 -82
  70. package/src/core/cli/index.ts +0 -1614
  71. package/src/core/cli/planner.ts +0 -656
  72. package/src/core/cli/plugin.ts +0 -117
  73. package/src/core/cli/propagate.ts +0 -97
  74. package/src/core/cli/root-help.ts +0 -342
  75. package/src/core/cli/root-surface.ts +0 -87
  76. package/src/core/cli/runtime-preflight.ts +0 -456
  77. package/src/core/completion/index.ts +0 -138
  78. package/src/core/completion/shells/bash.ts +0 -459
  79. package/src/core/completion/shells/fish.ts +0 -259
  80. package/src/core/completion/shells/powershell.ts +0 -439
  81. package/src/core/completion/shells/shared.ts +0 -310
  82. package/src/core/completion/shells/zsh.ts +0 -381
  83. package/src/core/config/index.ts +0 -417
  84. package/src/core/config/package-json.ts +0 -560
  85. package/src/core/errors/index.ts +0 -193
  86. package/src/core/execution/index.ts +0 -265
  87. package/src/core/help/ansi.ts +0 -144
  88. package/src/core/help/index.ts +0 -563
  89. package/src/core/json-schema/index.ts +0 -910
  90. package/src/core/json-schema/meta-descriptions.generated.ts +0 -202
  91. package/src/core/output/activity.ts +0 -575
  92. package/src/core/output/bind.ts +0 -59
  93. package/src/core/output/contracts.ts +0 -194
  94. package/src/core/output/display-value.ts +0 -48
  95. package/src/core/output/index.ts +0 -704
  96. package/src/core/output/renderers.ts +0 -125
  97. package/src/core/output/writer.ts +0 -46
  98. package/src/core/parse/index.ts +0 -742
  99. package/src/core/prompt/index.ts +0 -623
  100. package/src/core/resolve/args.ts +0 -144
  101. package/src/core/resolve/coerce.ts +0 -500
  102. package/src/core/resolve/config.ts +0 -26
  103. package/src/core/resolve/contracts.ts +0 -135
  104. package/src/core/resolve/errors.ts +0 -227
  105. package/src/core/resolve/flags.ts +0 -269
  106. package/src/core/resolve/index.ts +0 -108
  107. package/src/core/resolve/property.ts +0 -99
  108. package/src/core/schema/activity.ts +0 -240
  109. package/src/core/schema/arg.ts +0 -841
  110. package/src/core/schema/command.ts +0 -1500
  111. package/src/core/schema/flag.ts +0 -917
  112. package/src/core/schema/index.ts +0 -96
  113. package/src/core/schema/middleware.ts +0 -171
  114. package/src/core/schema/number-constraints.ts +0 -153
  115. package/src/core/schema/prompt.ts +0 -171
  116. package/src/core/schema/run.ts +0 -198
  117. package/src/core/schema-dsl/index.ts +0 -109
  118. package/src/core/schema-dsl/parse.ts +0 -262
  119. package/src/core/schema-dsl/runtime.ts +0 -609
  120. package/src/core/schema-dsl/to-json-schema.ts +0 -102
  121. package/src/core/testkit/index.ts +0 -147
  122. package/src/index.ts +0 -181
  123. package/src/runtime/adapter.ts +0 -303
  124. package/src/runtime/auto.ts +0 -86
  125. package/src/runtime/bun.ts +0 -48
  126. package/src/runtime/deno.ts +0 -367
  127. package/src/runtime/detect.ts +0 -105
  128. package/src/runtime/index.ts +0 -21
  129. package/src/runtime/node-builtins.d.ts +0 -27
  130. package/src/runtime/node.ts +0 -289
  131. package/src/runtime/paths.ts +0 -64
  132. package/src/runtime/support.ts +0 -77
  133. package/src/runtime.ts +0 -31
  134. package/src/schema.ts +0 -16
  135. package/src/strings.ts +0 -34
  136. package/src/testkit.ts +0 -25
  137. package/src/version.ts +0 -20
@@ -1,2 +1,122 @@
1
- const e=/\u001B(?:\[[0-?]*[ -/]*[@-~]|\][^\u0007\u001B]*(?:\u0007|\u001B\\))/g;function t(t){return t.replace(e,``)}function n(e){return t(e).length}function r(e,t){return`]8;;${e instanceof URL?e.href:e}${t}]8;;`}function i(e,t){let r=n(e);return r>=t?e:e+` `.repeat(t-r)}function a(e,t,r){if(n(e)+r<=t)return e;let i=t-r;if(i<=0)return e;let a=e.split(` `),o=[],s=``,c=0;for(let e of a){let t=n(e);s.length===0?(s=e,c=t):c+1+t<=i?(s+=` ${e}`,c+=1+t):(o.push(s),s=e,c=t)}s.length>0&&o.push(s);let l=` `.repeat(r);return o.map((e,t)=>t===0?e:`${l}${e}`).join(`
2
- `)}export{r as osc8,i as padEnd,n as visibleWidth,a as wrapText};
1
+ //#region src/core/help/ansi.ts
2
+ /**
3
+ * ANSI/OSC-aware text helpers for help formatting.
4
+ *
5
+ * Terminal escape sequences (SGR colors, OSC 8 hyperlinks) occupy zero
6
+ * columns when rendered, so width math must measure the *visible* text.
7
+ * {@linkcode visibleWidth} strips escapes before counting, and the shared
8
+ * {@linkcode padEnd}/{@linkcode wrapText} helpers build on it so aligned
9
+ * tables and wrapped lines stay intact when escapes are present.
10
+ *
11
+ * @module dreamcli/core/help/ansi
12
+ */
13
+ /**
14
+ * Matches ANSI escape sequences: CSI (e.g. SGR color codes like `\x1b[31m`)
15
+ * and OSC (e.g. OSC 8 hyperlinks), with both BEL and ST terminators.
16
+ *
17
+ * @internal
18
+ */
19
+ const ANSI_PATTERN = /\u001B(?:\[[0-?]*[ -/]*[@-~]|\][^\u0007\u001B]*(?:\u0007|\u001B\\))/g;
20
+ /**
21
+ * Remove ANSI CSI and OSC escape sequences from `text`.
22
+ *
23
+ * @param text - Text possibly containing terminal escapes.
24
+ * @returns The text with all escape sequences removed.
25
+ */
26
+ function stripAnsi(text) {
27
+ return text.replace(ANSI_PATTERN, "");
28
+ }
29
+ /**
30
+ * Measure the visible column width of `text`, ignoring ANSI/OSC escapes.
31
+ *
32
+ * Escape sequences (SGR colors, OSC 8 hyperlinks) occupy zero columns when
33
+ * rendered, so `.length` overcounts whenever they are present. Help
34
+ * formatting uses this for padding and wrapping; exported for custom help
35
+ * renderers that mix colors or links into aligned output.
36
+ *
37
+ * @param text - Text possibly containing terminal escapes.
38
+ * @returns Number of visible characters.
39
+ *
40
+ * @example
41
+ * ```ts
42
+ * visibleWidth('plain'); // 5
43
+ * visibleWidth(osc8('https://x.dev', 'x')); // 1
44
+ * ```
45
+ */
46
+ function visibleWidth(text) {
47
+ return stripAnsi(text).length;
48
+ }
49
+ const OSC = "\x1B]";
50
+ const BEL = "\x07";
51
+ /**
52
+ * Wrap `text` in an [OSC 8 hyperlink](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda)
53
+ * pointing at `url`.
54
+ *
55
+ * Supporting terminals render `text` as a clickable link; non-supporting
56
+ * terminals ignore the escape sequence and show plain text. Combine with
57
+ * {@linkcode visibleWidth}-aware formatting when embedding links in aligned
58
+ * output.
59
+ *
60
+ * @param url - Link target (string or `URL` instance).
61
+ * @param text - Visible link text.
62
+ * @returns The OSC 8 escape sequence wrapping `text`.
63
+ *
64
+ * @example
65
+ * ```ts
66
+ * cli('mycli').version(osc8('https://github.com/me/mycli/releases/tag/v1.0.0', '1.0.0'));
67
+ * ```
68
+ */
69
+ function osc8(url, text) {
70
+ return `${OSC}8;;${url instanceof URL ? url.href : url}${BEL}${text}${OSC}8;;${BEL}`;
71
+ }
72
+ /**
73
+ * Pad `text` to `length` visible columns with trailing spaces.
74
+ *
75
+ * @param text - The string to pad (may contain ANSI/OSC escapes).
76
+ * @param length - Target visible width in columns.
77
+ * @returns The padded string, unchanged if already at or beyond `length`.
78
+ */
79
+ function padEnd(text, length) {
80
+ const visible = visibleWidth(text);
81
+ if (visible >= length) return text;
82
+ return text + " ".repeat(length - visible);
83
+ }
84
+ /**
85
+ * Wrap text to `width`, preserving leading indent on continuation lines.
86
+ *
87
+ * Line lengths are measured with {@linkcode visibleWidth}, so embedded
88
+ * ANSI/OSC escapes do not trigger premature wrapping.
89
+ *
90
+ * @param text - The text to wrap.
91
+ * @param width - Maximum line width in columns.
92
+ * @param indent - Number of leading spaces for continuation lines.
93
+ * @returns The wrapped string with newlines inserted as needed.
94
+ */
95
+ function wrapText(text, width, indent) {
96
+ if (visibleWidth(text) + indent <= width) return text;
97
+ const maxLen = width - indent;
98
+ if (maxLen <= 0) return text;
99
+ const words = text.split(" ");
100
+ const lines = [];
101
+ let current = "";
102
+ let currentWidth = 0;
103
+ for (const word of words) {
104
+ const wordWidth = visibleWidth(word);
105
+ if (current.length === 0) {
106
+ current = word;
107
+ currentWidth = wordWidth;
108
+ } else if (currentWidth + 1 + wordWidth <= maxLen) {
109
+ current += ` ${word}`;
110
+ currentWidth += 1 + wordWidth;
111
+ } else {
112
+ lines.push(current);
113
+ current = word;
114
+ currentWidth = wordWidth;
115
+ }
116
+ }
117
+ if (current.length > 0) lines.push(current);
118
+ const pad = " ".repeat(indent);
119
+ return lines.map((line, i) => i === 0 ? line : `${pad}${line}`).join("\n");
120
+ }
121
+ //#endregion
122
+ export { osc8, padEnd, visibleWidth, wrapText };
@@ -1,7 +1,329 @@
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(y(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(b(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?e.name:t.isDefaultHelp?t.binName:`${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){return v(`Flags:`,u(e),t.width)}function v(e,t,i){if(t.length===0)return``;let a=[e],o=0;for(let e of t){let t=` ${e.left}`;t.length>o&&(o=t.length)}let s=o+2;for(let e of t){let t=` ${e.left}`;if(e.description.length===0)a.push(t);else{let o=n(t,s),c=r(e.description,i,s);a.push(`${o}${c}`)}}return a.join(`
5
- `)}function y(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 b(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{v as formatFlagEntriesBlock,m as formatHelp,p as formatHelpSections};
1
+ import { getFlagAliasNames } from "../schema/flag.mjs";
2
+ import { formatDisplayValue } from "../output/display-value.mjs";
3
+ import { padEnd, wrapText } from "./ansi.mjs";
4
+ //#region src/core/help/index.ts
5
+ /**
6
+ * Auto-generated help text from command schemas.
7
+ *
8
+ * Renders usage line, description, positional args, flags table, and
9
+ * examples from a {@linkcode CommandSchema}. Designed for TTY output with
10
+ * configurable width.
11
+ *
12
+ * @module dreamcli/core/help
13
+ */
14
+ const DEFAULT_WIDTH = 80;
15
+ /**
16
+ * Apply defaults to optional {@link HelpOptions}.
17
+ *
18
+ * @param options - User-supplied help options, or `undefined` for all defaults.
19
+ * @returns Fully resolved options with defaults applied.
20
+ */
21
+ function resolveOptions(options) {
22
+ return {
23
+ width: options?.width ?? DEFAULT_WIDTH,
24
+ binName: options?.binName,
25
+ isDefaultHelp: options?.isDefaultHelp ?? false
26
+ };
27
+ }
28
+ /**
29
+ * Format a deprecation annotation for help text.
30
+ *
31
+ * @param deprecated - `true` for a generic marker, or a string explaining the deprecation.
32
+ * @returns Bracketed deprecation label, e.g. `[deprecated]` or `[deprecated: use --foo]`.
33
+ */
34
+ function formatDeprecated(deprecated) {
35
+ return typeof deprecated === "string" ? `[deprecated: ${deprecated}]` : "[deprecated]";
36
+ }
37
+ /** Format a default value for help output, preserving nullish sentinels. */
38
+ function formatHelpDefaultValue(value) {
39
+ if (value === void 0) return "undefined";
40
+ if (value === null) return "null";
41
+ return formatDisplayValue(value);
42
+ }
43
+ /**
44
+ * Format a flag's left column: `-a, --name <type>`.
45
+ *
46
+ * @param name - Long flag name (without `--` prefix).
47
+ * @param schema - The {@link FlagSchema} describing the flag.
48
+ * @returns Formatted left-column string for the flags table.
49
+ */
50
+ function formatFlagLeft(name, schema) {
51
+ const visibleShortAliases = getFlagAliasNames(schema, { kind: "short" });
52
+ const visibleLongAliases = getFlagAliasNames(schema, { kind: "long" });
53
+ const forms = [
54
+ ...visibleShortAliases.map((alias) => `-${alias}`),
55
+ `--${name}`,
56
+ ...visibleLongAliases.map((alias) => `--${alias}`)
57
+ ];
58
+ if (schema.kind !== "boolean") return `${forms.join(", ")} ${formatValueHint(schema)}`;
59
+ return forms.join(", ");
60
+ }
61
+ /**
62
+ * Produce a type hint like `<string>`, `<number>`, `<us|eu|ap>`.
63
+ *
64
+ * @param schema - The {@link FlagSchema} whose value type determines the hint.
65
+ * @returns Angle-bracketed hint string, or empty string for booleans.
66
+ */
67
+ function formatValueHint(schema) {
68
+ switch (schema.kind) {
69
+ case "string": return "<string>";
70
+ case "number": return "<number>";
71
+ case "enum": return `<${(schema.enumValues ?? []).join("|")}>`;
72
+ case "array": return `<${schema.elementSchema !== void 0 ? formatValueHint(schema.elementSchema).slice(1, -1) : "value"}>...`;
73
+ case "boolean": return "";
74
+ case "custom": return "<value>";
75
+ }
76
+ }
77
+ /**
78
+ * Build description with env/config/prompt/default/required/deprecated annotations.
79
+ *
80
+ * @param schema - The {@link FlagSchema} to describe.
81
+ * @returns Concatenated description string with metadata annotations.
82
+ */
83
+ function formatFlagDescription(schema) {
84
+ const parts = [];
85
+ if (schema.description !== void 0) parts.push(schema.description);
86
+ if (schema.deprecated !== void 0) parts.push(formatDeprecated(schema.deprecated));
87
+ if (schema.envVar !== void 0) parts.push(`[env: ${schema.envVar}]`);
88
+ if (schema.configPath !== void 0) parts.push(`[config: ${schema.configPath}]`);
89
+ if (schema.prompt !== void 0) parts.push("[prompt]");
90
+ if (schema.presence === "required") parts.push("[required]");
91
+ else if (schema.presence === "defaulted" && schema.kind !== "boolean") parts.push(`(default: ${formatHelpDefaultValue(schema.defaultValue)})`);
92
+ return parts.join(" ");
93
+ }
94
+ /**
95
+ * Build the flag entries sorted: short-aliased first, then alphabetical.
96
+ *
97
+ * @param flags - Map of flag names to {@link FlagSchema} definitions.
98
+ * @returns Sorted array of {@link FlagEntry} objects for the flags table.
99
+ */
100
+ function buildFlagEntries(flags) {
101
+ const names = Object.keys(flags);
102
+ if (names.length === 0) return [];
103
+ const sorted = [...names].sort((a, b) => {
104
+ const aSchema = flags[a];
105
+ const bSchema = flags[b];
106
+ if (aSchema === void 0 || bSchema === void 0) return 0;
107
+ const aHasShort = getFlagAliasNames(aSchema, { kind: "short" }).length > 0;
108
+ const bHasShort = getFlagAliasNames(bSchema, { kind: "short" }).length > 0;
109
+ if (aHasShort && !bHasShort) return -1;
110
+ if (!aHasShort && bHasShort) return 1;
111
+ return a.localeCompare(b);
112
+ });
113
+ const entries = [];
114
+ for (const name of sorted) {
115
+ const schema = flags[name];
116
+ if (schema === void 0) continue;
117
+ entries.push({
118
+ left: formatFlagLeft(name, schema),
119
+ description: formatFlagDescription(schema)
120
+ });
121
+ }
122
+ return entries;
123
+ }
124
+ /**
125
+ * Format a positional arg for the usage line.
126
+ *
127
+ * @param entry - The {@link CommandArgEntry} containing name and schema.
128
+ * @returns Bracketed arg token, e.g. `<file>` or `[output]...`.
129
+ */
130
+ function formatArgUsage(entry) {
131
+ const { name, schema } = entry;
132
+ const label = schema.kind === "enum" && schema.enumValues !== void 0 ? schema.enumValues.join("|") : name;
133
+ const variadicSuffix = schema.variadic ? "..." : "";
134
+ if (schema.presence === "required") return `<${label}>${variadicSuffix}`;
135
+ return `[${label}]${variadicSuffix}`;
136
+ }
137
+ /**
138
+ * Format arg description with annotations.
139
+ *
140
+ * @param schema - The {@link ArgSchema} to describe.
141
+ * @returns Concatenated description string with metadata annotations.
142
+ */
143
+ function formatArgDescription(schema) {
144
+ const parts = [];
145
+ if (schema.description !== void 0) parts.push(schema.description);
146
+ if (schema.deprecated !== void 0) parts.push(formatDeprecated(schema.deprecated));
147
+ if (schema.envVar !== void 0) parts.push(`[env: ${schema.envVar}]`);
148
+ if (schema.presence === "defaulted") parts.push(`(default: ${formatHelpDefaultValue(schema.defaultValue)})`);
149
+ return parts.join(" ");
150
+ }
151
+ /**
152
+ * Build the ordered help sections without joining them.
153
+ *
154
+ * @internal
155
+ * @param schema - The {@link CommandSchema} to render.
156
+ * @param options - Optional {@link HelpOptions} for width/bin name.
157
+ * @returns Array of section strings (usage, description, commands, args, flags, examples).
158
+ */
159
+ function formatHelpSections(schema, options) {
160
+ const opts = resolveOptions(options);
161
+ const sections = [];
162
+ sections.push(formatUsageLine(schema, opts));
163
+ if (schema.description !== void 0) sections.push(schema.description);
164
+ const visibleCommands = schema.commands.filter((c) => !c.hidden);
165
+ if (visibleCommands.length > 0) sections.push(formatCommandsSection(visibleCommands, opts));
166
+ if (schema.args.length > 0) sections.push(formatArgsSection(schema.args, opts));
167
+ if (Object.keys(schema.flags).length > 0) sections.push(formatFlagsSection(schema.flags, opts));
168
+ if (schema.examples.length > 0) sections.push(formatExamplesSection(schema.examples));
169
+ return sections;
170
+ }
171
+ /**
172
+ * Generate help text from a command schema.
173
+ *
174
+ * Low-level formatter: most applications reach this through `--help`,
175
+ * `help <command>`, or root help rendering in `CLIBuilder`. Call
176
+ * `formatHelp()` directly when embedding DreamCLI help text into custom UIs,
177
+ * tests, or generated docs.
178
+ *
179
+ * Sections rendered (in order):
180
+ * 1. **Usage** line — `program <command> [flags] <args>`
181
+ * 2. **Description** — the command's `.description()` text
182
+ * 3. **Commands** — subcommands table (if any, skips hidden)
183
+ * 4. **Arguments** — positional args table (if any)
184
+ * 5. **Flags** — flags table with type hints and defaults
185
+ * 6. **Examples** — usage examples (if any)
186
+ *
187
+ * @param schema - The command schema to render help for.
188
+ * @param options - Formatting options (width, binary name).
189
+ * @returns The formatted help string.
190
+ *
191
+ * @example
192
+ * ```ts
193
+ * const text = formatHelp(deploy.schema, { binName: 'mycli' });
194
+ * ```
195
+ */
196
+ function formatHelp(schema, options) {
197
+ return `${formatHelpSections(schema, options).join("\n\n")}\n`;
198
+ }
199
+ /**
200
+ * Render the `Usage:` line for a command.
201
+ *
202
+ * @param schema - The {@link CommandSchema} to summarize.
203
+ * @param opts - Resolved help options (bin name, default-help flag).
204
+ * @returns Single-line usage string, e.g. `Usage: mycli deploy [flags] <env>`.
205
+ */
206
+ function formatUsageLine(schema, opts) {
207
+ const parts = ["Usage:"];
208
+ const cmdName = opts.binName === void 0 ? schema.name : opts.isDefaultHelp ? opts.binName : `${opts.binName} ${schema.name}`;
209
+ parts.push(cmdName);
210
+ if (schema.commands.length > 0) parts.push("<command>");
211
+ if (Object.keys(schema.flags).length > 0) parts.push("[flags]");
212
+ for (const entry of schema.args) parts.push(formatArgUsage(entry));
213
+ return parts.join(" ");
214
+ }
215
+ /**
216
+ * Render the `Arguments:` help section.
217
+ *
218
+ * @param args - Positional arg entries from the {@link CommandSchema}.
219
+ * @param opts - Resolved help options for line-width wrapping.
220
+ * @returns Multi-line arguments section string.
221
+ */
222
+ function formatArgsSection(args, opts) {
223
+ const lines = ["Arguments:"];
224
+ const GAP = 2;
225
+ let maxLeft = 0;
226
+ const entries = [];
227
+ for (const entry of args) {
228
+ const left = ` ${formatArgUsage(entry)}`;
229
+ const desc = formatArgDescription(entry.schema);
230
+ entries.push({
231
+ left,
232
+ desc
233
+ });
234
+ if (left.length > maxLeft) maxLeft = left.length;
235
+ }
236
+ const descCol = maxLeft + GAP;
237
+ for (const { left, desc } of entries) if (desc.length === 0) lines.push(left);
238
+ else {
239
+ const padded = padEnd(left, descCol);
240
+ const wrapped = wrapText(desc, opts.width, descCol);
241
+ lines.push(`${padded}${wrapped}`);
242
+ }
243
+ return lines.join("\n");
244
+ }
245
+ /**
246
+ * Render the `Flags:` help section.
247
+ *
248
+ * @param flags - Map of flag names to {@link FlagSchema} definitions.
249
+ * @param opts - Resolved help options for line-width wrapping.
250
+ * @returns Multi-line flags section string.
251
+ */
252
+ function formatFlagsSection(flags, opts) {
253
+ return formatFlagEntriesBlock("Flags:", buildFlagEntries(flags), opts.width);
254
+ }
255
+ /**
256
+ * Render a titled two-column flag block from pre-built {@link FlagEntry} rows.
257
+ *
258
+ * Shared by the per-command `Flags:` section and the root-help `Global options:`
259
+ * block (built-in flags), so column alignment and description wrapping stay
260
+ * identical across both. Returns `''` when there are no entries.
261
+ *
262
+ * @param title - Section heading (e.g. `'Flags:'`, `'Global options:'`).
263
+ * @param entries - Formatted left/description rows.
264
+ * @param width - Terminal width for description wrapping.
265
+ * @returns Multi-line block string, or `''` when `entries` is empty.
266
+ * @internal
267
+ */
268
+ function formatFlagEntriesBlock(title, entries, width) {
269
+ if (entries.length === 0) return "";
270
+ const lines = [title];
271
+ const GAP = 2;
272
+ let maxLeft = 0;
273
+ for (const entry of entries) {
274
+ const indented = ` ${entry.left}`;
275
+ if (indented.length > maxLeft) maxLeft = indented.length;
276
+ }
277
+ const descCol = maxLeft + GAP;
278
+ for (const entry of entries) {
279
+ const left = ` ${entry.left}`;
280
+ if (entry.description.length === 0) lines.push(left);
281
+ else {
282
+ const padded = padEnd(left, descCol);
283
+ const wrapped = wrapText(entry.description, width, descCol);
284
+ lines.push(`${padded}${wrapped}`);
285
+ }
286
+ }
287
+ return lines.join("\n");
288
+ }
289
+ /**
290
+ * Render the `Commands:` help section.
291
+ *
292
+ * @param commands - Visible subcommand schemas (hidden commands pre-filtered).
293
+ * @param opts - Resolved help options for line-width wrapping.
294
+ * @returns Multi-line commands section string.
295
+ */
296
+ function formatCommandsSection(commands, opts) {
297
+ const lines = ["Commands:"];
298
+ const GAP = 2;
299
+ let maxNameLen = 0;
300
+ for (const cmd of commands) if (cmd.name.length > maxNameLen) maxNameLen = cmd.name.length;
301
+ const descCol = 2 + maxNameLen + GAP;
302
+ for (const cmd of commands) {
303
+ const left = ` ${cmd.name}`;
304
+ const desc = cmd.description ?? "";
305
+ if (desc.length === 0) lines.push(left);
306
+ else {
307
+ const padded = padEnd(left, descCol);
308
+ const wrapped = wrapText(desc, opts.width, descCol);
309
+ lines.push(`${padded}${wrapped}`);
310
+ }
311
+ }
312
+ return lines.join("\n");
313
+ }
314
+ /**
315
+ * Render the `Examples:` help section.
316
+ *
317
+ * @param examples - Array of {@link CommandExample} entries.
318
+ * @returns Multi-line examples section string.
319
+ */
320
+ function formatExamplesSection(examples) {
321
+ const lines = ["Examples:"];
322
+ for (const example of examples) if (example.description !== void 0) {
323
+ lines.push(` ${example.description}:`);
324
+ lines.push(` $ ${example.command}`);
325
+ } else lines.push(` $ ${example.command}`);
326
+ return lines.join("\n");
327
+ }
328
+ //#endregion
329
+ export { formatFlagEntriesBlock, formatHelp, formatHelpSections };