@kjanat/dreamcli 3.0.0-rc.1 → 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 (194) hide show
  1. package/CHANGELOG.md +217 -1
  2. package/dist/core/cli/dispatch.d.mts +6 -5
  3. package/dist/core/cli/dispatch.mjs +205 -1
  4. package/dist/core/cli/help-links.d.mts +0 -1
  5. package/dist/core/cli/help-links.mjs +41 -1
  6. package/dist/core/cli/index.d.mts +81 -8
  7. package/dist/core/cli/index.mjs +945 -1
  8. package/dist/core/cli/planner.d.mts +5 -1
  9. package/dist/core/cli/planner.mjs +300 -1
  10. package/dist/core/cli/plugin.d.mts +1 -1
  11. package/dist/core/cli/plugin.mjs +41 -1
  12. package/dist/core/cli/propagate.d.mts +1 -1
  13. package/dist/core/cli/propagate.mjs +57 -1
  14. package/dist/core/cli/root-help.d.mts +2 -1
  15. package/dist/core/cli/root-help.mjs +226 -4
  16. package/dist/core/cli/root-surface.d.mts +12 -1
  17. package/dist/core/cli/root-surface.mjs +28 -1
  18. package/dist/core/cli/runtime-preflight.d.mts +14 -2
  19. package/dist/core/cli/runtime-preflight.mjs +169 -1
  20. package/dist/core/completion/index.d.mts +0 -1
  21. package/dist/core/completion/index.mjs +90 -1
  22. package/dist/core/completion/shells/bash.d.mts +0 -1
  23. package/dist/core/completion/shells/bash.mjs +308 -3
  24. package/dist/core/completion/shells/fish.d.mts +0 -1
  25. package/dist/core/completion/shells/fish.mjs +162 -2
  26. package/dist/core/completion/shells/powershell.d.mts +0 -1
  27. package/dist/core/completion/shells/powershell.mjs +358 -2
  28. package/dist/core/completion/shells/shared.d.mts +13 -2
  29. package/dist/core/completion/shells/shared.mjs +176 -1
  30. package/dist/core/completion/shells/zsh.d.mts +0 -1
  31. package/dist/core/completion/shells/zsh.mjs +251 -2
  32. package/dist/core/config/index.d.mts +2 -3
  33. package/dist/core/config/index.mjs +246 -1
  34. package/dist/core/config/package-json.d.mts +27 -4
  35. package/dist/core/config/package-json.mjs +386 -3
  36. package/dist/core/errors/index.d.mts +3 -3
  37. package/dist/core/errors/index.mjs +87 -1
  38. package/dist/core/execution/index.d.mts +0 -1
  39. package/dist/core/execution/index.mjs +201 -1
  40. package/dist/core/help/ansi.d.mts +11 -5
  41. package/dist/core/help/ansi.mjs +121 -2
  42. package/dist/core/help/index.d.mts +22 -3
  43. package/dist/core/help/index.mjs +341 -7
  44. package/dist/core/help/theme.d.mts +68 -0
  45. package/dist/core/help/theme.mjs +46 -0
  46. package/dist/core/json-schema/index.d.mts +15 -2
  47. package/dist/core/json-schema/index.mjs +536 -12
  48. package/dist/core/json-schema/meta-descriptions.generated.d.mts +55 -38
  49. package/dist/core/json-schema/meta-descriptions.generated.mjs +102 -28
  50. package/dist/core/output/activity.d.mts +0 -1
  51. package/dist/core/output/activity.mjs +452 -1
  52. package/dist/core/output/bind.mjs +56 -1
  53. package/dist/core/output/contracts.d.mts +4 -5
  54. package/dist/core/output/contracts.mjs +57 -1
  55. package/dist/core/output/display-value.mjs +32 -1
  56. package/dist/core/output/index.d.mts +21 -1
  57. package/dist/core/output/index.mjs +442 -2
  58. package/dist/core/output/renderers.d.mts +0 -1
  59. package/dist/core/output/renderers.mjs +46 -1
  60. package/dist/core/output/writer.mjs +12 -1
  61. package/dist/core/parse/index.d.mts +40 -7
  62. package/dist/core/parse/index.mjs +727 -1
  63. package/dist/core/prompt/index.d.mts +1 -1
  64. package/dist/core/prompt/index.mjs +348 -6
  65. package/dist/core/resolve/args.d.mts +1 -1
  66. package/dist/core/resolve/args.mjs +105 -1
  67. package/dist/core/resolve/coerce.d.mts +1 -1
  68. package/dist/core/resolve/coerce.mjs +336 -1
  69. package/dist/core/resolve/config.mjs +19 -1
  70. package/dist/core/resolve/contracts.d.mts +9 -4
  71. package/dist/core/resolve/errors.d.mts +0 -1
  72. package/dist/core/resolve/errors.mjs +140 -2
  73. package/dist/core/resolve/flags.d.mts +7 -2
  74. package/dist/core/resolve/flags.mjs +251 -1
  75. package/dist/core/resolve/index.d.mts +2 -2
  76. package/dist/core/resolve/index.mjs +85 -1
  77. package/dist/core/resolve/property.d.mts +4 -2
  78. package/dist/core/resolve/property.mjs +53 -1
  79. package/dist/core/schema/activity.d.mts +31 -11
  80. package/dist/core/schema/arg.d.mts +3 -4
  81. package/dist/core/schema/arg.mjs +463 -1
  82. package/dist/core/schema/command.d.mts +26 -6
  83. package/dist/core/schema/command.mjs +726 -1
  84. package/dist/core/schema/flag.d.mts +485 -19
  85. package/dist/core/schema/flag.mjs +705 -1
  86. package/dist/core/schema/index.d.mts +4 -2
  87. package/dist/core/schema/middleware.d.mts +4 -3
  88. package/dist/core/schema/middleware.mjs +41 -1
  89. package/dist/core/schema/number-constraints.mjs +60 -1
  90. package/dist/core/schema/prompt.d.mts +6 -3
  91. package/dist/core/schema/run.d.mts +20 -1
  92. package/dist/core/schema/string-constraints.d.mts +97 -0
  93. package/dist/core/schema/string-constraints.mjs +69 -0
  94. package/dist/core/schema/value-parsers.d.mts +78 -0
  95. package/dist/core/schema/value-parsers.mjs +142 -0
  96. package/dist/core/schema-dsl/runtime.mjs +271 -2
  97. package/dist/core/schema-dsl/to-json-schema.d.mts +0 -1
  98. package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
  99. package/dist/core/testkit/index.d.mts +0 -31
  100. package/dist/core/testkit/index.mjs +83 -1
  101. package/dist/index.d.mts +11 -6
  102. package/dist/index.mjs +22 -1
  103. package/dist/runtime/adapter.d.mts +38 -2
  104. package/dist/runtime/adapter.mjs +87 -1
  105. package/dist/runtime/auto.d.mts +2 -3
  106. package/dist/runtime/auto.mjs +45 -1
  107. package/dist/runtime/deno.d.mts +24 -5
  108. package/dist/runtime/deno.mjs +262 -2
  109. package/dist/runtime/detect.mjs +45 -1
  110. package/dist/runtime/index.d.mts +3 -4
  111. package/dist/runtime/node.d.mts +8 -2
  112. package/dist/runtime/node.mjs +220 -2
  113. package/dist/runtime/paths.mjs +48 -1
  114. package/dist/runtime.d.mts +4 -4
  115. package/dist/runtime.mjs +6 -1
  116. package/dist/strings.mjs +22 -1
  117. package/dist/testkit.d.mts +1 -0
  118. package/dist/testkit.mjs +5 -1
  119. package/dist/version.d.mts +7 -3
  120. package/dist/version.mjs +7 -1
  121. package/dreamcli.schema.json +36 -7
  122. package/package.json +45 -42
  123. package/dist/runtime/bun.d.mts +0 -28
  124. package/dist/runtime/bun.mjs +0 -1
  125. package/src/core/cli/dispatch.ts +0 -355
  126. package/src/core/cli/help-links.ts +0 -82
  127. package/src/core/cli/index.ts +0 -1614
  128. package/src/core/cli/planner.ts +0 -656
  129. package/src/core/cli/plugin.ts +0 -117
  130. package/src/core/cli/propagate.ts +0 -97
  131. package/src/core/cli/root-help.ts +0 -342
  132. package/src/core/cli/root-surface.ts +0 -87
  133. package/src/core/cli/runtime-preflight.ts +0 -456
  134. package/src/core/completion/index.ts +0 -138
  135. package/src/core/completion/shells/bash.ts +0 -459
  136. package/src/core/completion/shells/fish.ts +0 -259
  137. package/src/core/completion/shells/powershell.ts +0 -439
  138. package/src/core/completion/shells/shared.ts +0 -310
  139. package/src/core/completion/shells/zsh.ts +0 -381
  140. package/src/core/config/index.ts +0 -417
  141. package/src/core/config/package-json.ts +0 -560
  142. package/src/core/errors/index.ts +0 -193
  143. package/src/core/execution/index.ts +0 -265
  144. package/src/core/help/ansi.ts +0 -144
  145. package/src/core/help/index.ts +0 -563
  146. package/src/core/json-schema/index.ts +0 -910
  147. package/src/core/json-schema/meta-descriptions.generated.ts +0 -202
  148. package/src/core/output/activity.ts +0 -575
  149. package/src/core/output/bind.ts +0 -59
  150. package/src/core/output/contracts.ts +0 -194
  151. package/src/core/output/display-value.ts +0 -48
  152. package/src/core/output/index.ts +0 -704
  153. package/src/core/output/renderers.ts +0 -125
  154. package/src/core/output/writer.ts +0 -46
  155. package/src/core/parse/index.ts +0 -742
  156. package/src/core/prompt/index.ts +0 -623
  157. package/src/core/resolve/args.ts +0 -144
  158. package/src/core/resolve/coerce.ts +0 -500
  159. package/src/core/resolve/config.ts +0 -26
  160. package/src/core/resolve/contracts.ts +0 -135
  161. package/src/core/resolve/errors.ts +0 -227
  162. package/src/core/resolve/flags.ts +0 -269
  163. package/src/core/resolve/index.ts +0 -108
  164. package/src/core/resolve/property.ts +0 -99
  165. package/src/core/schema/activity.ts +0 -240
  166. package/src/core/schema/arg.ts +0 -841
  167. package/src/core/schema/command.ts +0 -1500
  168. package/src/core/schema/flag.ts +0 -917
  169. package/src/core/schema/index.ts +0 -96
  170. package/src/core/schema/middleware.ts +0 -171
  171. package/src/core/schema/number-constraints.ts +0 -153
  172. package/src/core/schema/prompt.ts +0 -171
  173. package/src/core/schema/run.ts +0 -198
  174. package/src/core/schema-dsl/index.ts +0 -109
  175. package/src/core/schema-dsl/parse.ts +0 -262
  176. package/src/core/schema-dsl/runtime.ts +0 -609
  177. package/src/core/schema-dsl/to-json-schema.ts +0 -102
  178. package/src/core/testkit/index.ts +0 -147
  179. package/src/index.ts +0 -181
  180. package/src/runtime/adapter.ts +0 -303
  181. package/src/runtime/auto.ts +0 -86
  182. package/src/runtime/bun.ts +0 -48
  183. package/src/runtime/deno.ts +0 -367
  184. package/src/runtime/detect.ts +0 -105
  185. package/src/runtime/index.ts +0 -21
  186. package/src/runtime/node-builtins.d.ts +0 -27
  187. package/src/runtime/node.ts +0 -289
  188. package/src/runtime/paths.ts +0 -64
  189. package/src/runtime/support.ts +0 -77
  190. package/src/runtime.ts +0 -31
  191. package/src/schema.ts +0 -16
  192. package/src/strings.ts +0 -34
  193. package/src/testkit.ts +0 -25
  194. 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(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 { 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 };