@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 +1,201 @@
1
- import{CLIError as e}from"../errors/index.mjs";import{formatHelp as t}from"../help/index.mjs";import{clearRequestedExitCode as n,getRequestedExitCode as r}from"../output/index.mjs";import{includesBeforeSeparator as i,parse as a}from"../parse/index.mjs";import{createTestPrompter as o}from"../prompt/index.mjs";import{resolve as s}from"../resolve/index.mjs";async function c(c){let{argv:f,command:m,meta:h,options:g,out:_,schema:v}=c;n(_);try{if(i(f,`--help`)||i(f,`-h`)){let e=t(v,g?.help);return _.log(e),{exitCode:0,error:void 0}}let n=m.handler;if(n===void 0){let t=new e(`Command '${m.schema.name}' has no action handler`,{code:`NO_ACTION`,suggest:`Add an .action() handler to the '${m.schema.name}' command`});return _.error(t.message),{exitCode:1,error:t}}await l(g?.plugins,{argv:f,command:v,meta:h,out:_});let c=a(v,f),y=g?.prompter??(g?.answers===void 0?void 0:o(g.answers)),b=await s(v,c,{...g?.stdinData===void 0?{}:{stdinData:g.stdinData},...g?.env===void 0?{}:{env:g.env},...g?.config===void 0?{}:{config:g.config},...y===void 0?{}:{prompter:y}}),x={args:b.args,flags:b.flags,deprecations:b.deprecations,command:v,meta:h,out:_};await u(g?.plugins,`afterResolve`,x);for(let e of b.deprecations)_.warn(p(e));return await u(g?.plugins,`beforeAction`,x),await d(m,n,b.flags,b.args,_,h),await u(g?.plugins,`afterAction`,x),{exitCode:r(_)??0,error:void 0}}catch(t){if(t instanceof e)return g?.jsonMode===!0?_.json({error:t.toJSON()}):(_.error(t.message),t.suggest!==void 0&&_.error(`Suggestion: ${t.suggest}`)),{exitCode:t.exitCode,error:t};let n=new e(`Unexpected error: ${t instanceof Error?t.message:String(t)}`,{code:`UNEXPECTED_ERROR`,cause:t});return g?.jsonMode===!0?_.json({error:n.toJSON()}):_.error(n.message),{exitCode:1,error:n}}finally{_.stopActive(),n(_)}}async function l(e,t){if(e!==void 0)for(let n of e){let e=n.hooks.beforeParse;e!==void 0&&await e(t)}}async function u(e,t,n){if(e!==void 0)for(let r of e){let e=r.hooks[t];e!==void 0&&await e(n)}}async function d(t,n,r,i,a,o){let s=t._executionSteps,c=async e=>{await n({flags:r,args:i,ctx:e,out:a,meta:o})};for(let t=s.length-1;t>=0;t--){let n=s[t];if(n===void 0)continue;let l=c;switch(n.kind){case`derive`:c=async t=>{let s=await n.handler({args:i,flags:r,ctx:t,out:a,meta:o});if(s===void 0){await l(t);return}if(typeof s!=`object`||!s||Array.isArray(s))throw new e(`derive() must return an object or undefined`,{code:`INVALID_BUILDER_STATE`,suggest:`Return an object to add context, or return nothing for validation-only derive handlers`});await l({...t,...s})};break;case`middleware`:c=async e=>{await n.handler({args:i,flags:r,ctx:e,out:a,meta:o,next:async t=>{await l({...e,...t})}})};break}}await c({})}function f(e,t){return{exitCode:e.exitCode,stdout:t.stdout,stderr:t.stderr,activity:t.activity,error:e.error}}function p(e){let t=e.kind===`flag`?`flag --${e.name}`:`argument <${e.name}>`;return typeof e.message==`string`?`Warning: ${t} is deprecated: ${e.message}`:`Warning: ${t} is deprecated`}export{f as buildRunResult,c as executeCommand};
1
+ import { CLIError } from "../errors/index.mjs";
2
+ import { includesBeforeSeparator, parse } from "../parse/index.mjs";
3
+ import { formatHelp } from "../help/index.mjs";
4
+ import { generateCommandSchema } from "../json-schema/index.mjs";
5
+ import { clearRequestedExitCode, getRequestedExitCode } from "../output/index.mjs";
6
+ import { createTestPrompter } from "../prompt/index.mjs";
7
+ import { resolve } from "../resolve/index.mjs";
8
+ //#region src/core/execution/index.ts
9
+ /**
10
+ * Run the full parse -> resolve -> plugin -> handler pipeline for one command.
11
+ *
12
+ * Handles `--help` short-circuit, plugin lifecycle hooks, deprecation warnings,
13
+ * and error wrapping. Both CLI dispatch and testkit `runCommand` converge here.
14
+ * @internal
15
+ */
16
+ async function executeCommand(request) {
17
+ const { argv, command, meta, options, out, schema } = request;
18
+ clearRequestedExitCode(out);
19
+ try {
20
+ if (includesBeforeSeparator(argv, "--help") || includesBeforeSeparator(argv, "-h")) {
21
+ if (out.jsonMode || options?.jsonMode === true) {
22
+ out.json(generateCommandSchema(schema));
23
+ return {
24
+ exitCode: 0,
25
+ error: void 0
26
+ };
27
+ }
28
+ const helpText = formatHelp(schema, options?.help?.colors !== void 0 ? options.help : {
29
+ ...options?.help,
30
+ colors: out.color
31
+ });
32
+ out.log(helpText);
33
+ return {
34
+ exitCode: 0,
35
+ error: void 0
36
+ };
37
+ }
38
+ const handler = command.handler;
39
+ if (handler === void 0) {
40
+ const error = new CLIError(`Command '${command.schema.name}' has no action handler`, {
41
+ code: "NO_ACTION",
42
+ suggest: `Add an .action() handler to the '${command.schema.name}' command`
43
+ });
44
+ out.error(error.message);
45
+ return {
46
+ exitCode: 1,
47
+ error
48
+ };
49
+ }
50
+ await runBeforeParseHooks(options?.plugins, {
51
+ argv,
52
+ command: schema,
53
+ meta,
54
+ out
55
+ });
56
+ const parsed = parse(schema, argv, options?.flags);
57
+ const effectivePrompter = options?.prompter ?? (options?.answers !== void 0 ? createTestPrompter(options.answers) : void 0);
58
+ const resolved = await resolve(schema, parsed, {
59
+ ...options?.stdinData !== void 0 ? { stdinData: options.stdinData } : {},
60
+ ...options?.env !== void 0 ? { env: options.env } : {},
61
+ ...options?.config !== void 0 ? { config: options.config } : {},
62
+ ...effectivePrompter !== void 0 ? { prompter: effectivePrompter } : {},
63
+ ...options?.stat !== void 0 ? { stat: options.stat } : {}
64
+ });
65
+ const resolvedParams = {
66
+ args: resolved.args,
67
+ flags: resolved.flags,
68
+ deprecations: resolved.deprecations,
69
+ command: schema,
70
+ meta,
71
+ out
72
+ };
73
+ await runResolvedHooks(options?.plugins, "afterResolve", resolvedParams);
74
+ for (const deprecation of resolved.deprecations) out.warn(formatDeprecation(deprecation));
75
+ await runResolvedHooks(options?.plugins, "beforeAction", resolvedParams);
76
+ await executeWithExecutionSteps(command, handler, resolved.flags, resolved.args, out, meta);
77
+ await runResolvedHooks(options?.plugins, "afterAction", resolvedParams);
78
+ return {
79
+ exitCode: getRequestedExitCode(out) ?? 0,
80
+ error: void 0
81
+ };
82
+ } catch (error) {
83
+ if (error instanceof CLIError) {
84
+ if (options?.jsonMode === true) out.json({ error: error.toJSON() });
85
+ else {
86
+ out.error(error.message);
87
+ if (error.suggest !== void 0) out.error(`Suggestion: ${error.suggest}`);
88
+ }
89
+ return {
90
+ exitCode: error.exitCode,
91
+ error
92
+ };
93
+ }
94
+ const wrapped = new CLIError(`Unexpected error: ${error instanceof Error ? error.message : String(error)}`, {
95
+ code: "UNEXPECTED_ERROR",
96
+ cause: error
97
+ });
98
+ if (options?.jsonMode === true) out.json({ error: wrapped.toJSON() });
99
+ else out.error(wrapped.message);
100
+ return {
101
+ exitCode: 1,
102
+ error: wrapped
103
+ };
104
+ } finally {
105
+ out.stopActive();
106
+ clearRequestedExitCode(out);
107
+ }
108
+ }
109
+ async function runBeforeParseHooks(plugins, params) {
110
+ if (plugins === void 0) return;
111
+ for (const current of plugins) {
112
+ const hook = current.hooks.beforeParse;
113
+ if (hook !== void 0) await hook(params);
114
+ }
115
+ }
116
+ async function runResolvedHooks(plugins, hookName, params) {
117
+ if (plugins === void 0) return;
118
+ for (const current of plugins) {
119
+ const hook = current.hooks[hookName];
120
+ if (hook !== void 0) await hook(params);
121
+ }
122
+ }
123
+ async function executeWithExecutionSteps(command, handler, flags, args, out, meta) {
124
+ const steps = command._executionSteps;
125
+ let chain = async (ctx) => {
126
+ await handler({
127
+ flags,
128
+ args,
129
+ ctx,
130
+ out,
131
+ meta
132
+ });
133
+ };
134
+ for (let i = steps.length - 1; i >= 0; i--) {
135
+ const step = steps[i];
136
+ if (step === void 0) continue;
137
+ const downstream = chain;
138
+ switch (step.kind) {
139
+ case "derive":
140
+ chain = async (ctx) => {
141
+ const additions = await step.handler({
142
+ args,
143
+ flags,
144
+ ctx,
145
+ out,
146
+ meta
147
+ });
148
+ if (additions === void 0) {
149
+ await downstream(ctx);
150
+ return;
151
+ }
152
+ if (typeof additions !== "object" || additions === null || Array.isArray(additions)) throw new CLIError("derive() must return an object or undefined", {
153
+ code: "INVALID_BUILDER_STATE",
154
+ suggest: "Return an object to add context, or return nothing for validation-only derive handlers"
155
+ });
156
+ await downstream({
157
+ ...ctx,
158
+ ...additions
159
+ });
160
+ };
161
+ break;
162
+ case "middleware":
163
+ chain = async (ctx) => {
164
+ await step.handler({
165
+ args,
166
+ flags,
167
+ ctx,
168
+ out,
169
+ meta,
170
+ next: async (additions) => {
171
+ await downstream({
172
+ ...ctx,
173
+ ...additions
174
+ });
175
+ }
176
+ });
177
+ };
178
+ break;
179
+ }
180
+ }
181
+ await chain({});
182
+ }
183
+ /**
184
+ * Assemble a {@linkcode CommandExecutionResult} and captured output buffers into a public `RunResult`.
185
+ * @internal
186
+ */
187
+ function buildRunResult(result, captured) {
188
+ return {
189
+ exitCode: result.exitCode,
190
+ stdout: captured.stdout,
191
+ stderr: captured.stderr,
192
+ activity: captured.activity,
193
+ error: result.error
194
+ };
195
+ }
196
+ function formatDeprecation(deprecation) {
197
+ const entity = deprecation.kind === "flag" ? `flag --${deprecation.name}` : `argument <${deprecation.name}>`;
198
+ return typeof deprecation.message === "string" ? `Warning: ${entity} is deprecated: ${deprecation.message}` : `Warning: ${entity} is deprecated`;
199
+ }
200
+ //#endregion
201
+ export { buildRunResult, executeCommand };
@@ -13,6 +13,11 @@
13
13
  /**
14
14
  * Remove ANSI CSI and OSC escape sequences from `text`.
15
15
  *
16
+ * Delegates to `ansispeck`'s stripper, which handles SGR sequences and OSC
17
+ * hyperlinks under both terminators. Kept as a named export so help
18
+ * formatting and custom help renderers reach the width-aware helpers and
19
+ * their stripper through one module.
20
+ *
16
21
  * @param text - Text possibly containing terminal escapes.
17
22
  * @returns The text with all escape sequences removed.
18
23
  */
@@ -39,10 +44,10 @@ declare function visibleWidth(text: string): number;
39
44
  * Wrap `text` in an [OSC 8 hyperlink](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda)
40
45
  * pointing at `url`.
41
46
  *
42
- * Supporting terminals render `text` as a clickable link; non-supporting
43
- * terminals ignore the escape sequence and show plain text. Combine with
44
- * {@linkcode visibleWidth}-aware formatting when embedding links in aligned
45
- * output.
47
+ * Supporting terminals render `text` as a clickable link; others show it
48
+ * plain. `text` defaults to the URL, so an omitted label degrades to a
49
+ * usable address. The framework's help layer decides *whether* to link
50
+ * (`help.hyperlinks`); this always emits when called.
46
51
  *
47
52
  * @param url - Link target (string or `URL` instance).
48
53
  * @param text - Visible link text.
@@ -51,9 +56,10 @@ declare function visibleWidth(text: string): number;
51
56
  * @example
52
57
  * ```ts
53
58
  * cli('mycli').version(osc8('https://github.com/me/mycli/releases/tag/v1.0.0', '1.0.0'));
59
+ * osc8('https://dreamcli.kjanat.dev'); // linked, displayed as the URL
54
60
  * ```
55
61
  */
56
- declare function osc8(url: string | URL, text: string): string;
62
+ declare function osc8(url: string | URL, text?: string): string;
57
63
  /**
58
64
  * Pad `text` to `length` visible columns with trailing spaces.
59
65
  *
@@ -1,2 +1,121 @@
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
+ import { createColors, strip } from "ansispeck";
2
+ //#region src/core/help/ansi.ts
3
+ /**
4
+ * ANSI/OSC-aware text helpers for help formatting.
5
+ *
6
+ * Terminal escape sequences (SGR colors, OSC 8 hyperlinks) occupy zero
7
+ * columns when rendered, so width math must measure the *visible* text.
8
+ * {@linkcode visibleWidth} strips escapes before counting, and the shared
9
+ * {@linkcode padEnd}/{@linkcode wrapText} helpers build on it so aligned
10
+ * tables and wrapped lines stay intact when escapes are present.
11
+ *
12
+ * @module dreamcli/core/help/ansi
13
+ */
14
+ /**
15
+ * Remove ANSI CSI and OSC escape sequences from `text`.
16
+ *
17
+ * Delegates to `ansispeck`'s stripper, which handles SGR sequences and OSC
18
+ * hyperlinks under both terminators. Kept as a named export so help
19
+ * formatting and custom help renderers reach the width-aware helpers and
20
+ * their stripper through one module.
21
+ *
22
+ * @param text - Text possibly containing terminal escapes.
23
+ * @returns The text with all escape sequences removed.
24
+ */
25
+ function stripAnsi(text) {
26
+ return strip(text);
27
+ }
28
+ /**
29
+ * Measure the visible column width of `text`, ignoring ANSI/OSC escapes.
30
+ *
31
+ * Escape sequences (SGR colors, OSC 8 hyperlinks) occupy zero columns when
32
+ * rendered, so `.length` overcounts whenever they are present. Help
33
+ * formatting uses this for padding and wrapping; exported for custom help
34
+ * renderers that mix colors or links into aligned output.
35
+ *
36
+ * @param text - Text possibly containing terminal escapes.
37
+ * @returns Number of visible characters.
38
+ *
39
+ * @example
40
+ * ```ts
41
+ * visibleWidth('plain'); // 5
42
+ * visibleWidth(osc8('https://x.dev', 'x')); // 1
43
+ * ```
44
+ */
45
+ function visibleWidth(text) {
46
+ return stripAnsi(text).length;
47
+ }
48
+ const emitLink = createColors(false, true).link;
49
+ /**
50
+ * Wrap `text` in an [OSC 8 hyperlink](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda)
51
+ * pointing at `url`.
52
+ *
53
+ * Supporting terminals render `text` as a clickable link; others show it
54
+ * plain. `text` defaults to the URL, so an omitted label degrades to a
55
+ * usable address. The framework's help layer decides *whether* to link
56
+ * (`help.hyperlinks`); this always emits when called.
57
+ *
58
+ * @param url - Link target (string or `URL` instance).
59
+ * @param text - Visible link text.
60
+ * @returns The OSC 8 escape sequence wrapping `text`.
61
+ *
62
+ * @example
63
+ * ```ts
64
+ * cli('mycli').version(osc8('https://github.com/me/mycli/releases/tag/v1.0.0', '1.0.0'));
65
+ * osc8('https://dreamcli.kjanat.dev'); // linked, displayed as the URL
66
+ * ```
67
+ */
68
+ function osc8(url, text) {
69
+ return emitLink(url, text);
70
+ }
71
+ /**
72
+ * Pad `text` to `length` visible columns with trailing spaces.
73
+ *
74
+ * @param text - The string to pad (may contain ANSI/OSC escapes).
75
+ * @param length - Target visible width in columns.
76
+ * @returns The padded string, unchanged if already at or beyond `length`.
77
+ */
78
+ function padEnd(text, length) {
79
+ const visible = visibleWidth(text);
80
+ if (visible >= length) return text;
81
+ return text + " ".repeat(length - visible);
82
+ }
83
+ /**
84
+ * Wrap text to `width`, preserving leading indent on continuation lines.
85
+ *
86
+ * Line lengths are measured with {@linkcode visibleWidth}, so embedded
87
+ * ANSI/OSC escapes do not trigger premature wrapping.
88
+ *
89
+ * @param text - The text to wrap.
90
+ * @param width - Maximum line width in columns.
91
+ * @param indent - Number of leading spaces for continuation lines.
92
+ * @returns The wrapped string with newlines inserted as needed.
93
+ */
94
+ function wrapText(text, width, indent) {
95
+ if (visibleWidth(text) + indent <= width) return text;
96
+ const maxLen = width - indent;
97
+ if (maxLen <= 0) return text;
98
+ const words = text.split(" ");
99
+ const lines = [];
100
+ let current = "";
101
+ let currentWidth = 0;
102
+ for (const word of words) {
103
+ const wordWidth = visibleWidth(word);
104
+ if (current.length === 0) {
105
+ current = word;
106
+ currentWidth = wordWidth;
107
+ } else if (currentWidth + 1 + wordWidth <= maxLen) {
108
+ current += ` ${word}`;
109
+ currentWidth += 1 + wordWidth;
110
+ } else {
111
+ lines.push(current);
112
+ current = word;
113
+ currentWidth = wordWidth;
114
+ }
115
+ }
116
+ if (current.length > 0) lines.push(current);
117
+ const pad = " ".repeat(indent);
118
+ return lines.map((line, i) => i === 0 ? line : `${pad}${line}`).join("\n");
119
+ }
120
+ //#endregion
121
+ export { osc8, padEnd, stripAnsi, visibleWidth, wrapText };
@@ -1,6 +1,8 @@
1
+ import { HelpTheme, HelpThemeFactory } from "./theme.mjs";
1
2
  import { osc8, visibleWidth } from "./ansi.mjs";
2
3
  import { CommandSchema } from "../schema/command.mjs";
3
-
4
+ import "../schema/index.mjs";
5
+ import { Colors } from "ansispeck";
4
6
  //#region src/core/help/index.d.ts
5
7
  /** Options for customising help output. */
6
8
  interface HelpOptions {
@@ -15,8 +17,55 @@ interface HelpOptions {
15
17
  * automatically when stdout is a TTY.
16
18
  */
17
19
  readonly hyperlinks?: boolean;
20
+ /**
21
+ * Render the default command's arguments and flags inline in root help.
22
+ *
23
+ * Only affects root-level help. When `false`, root help lists commands and
24
+ * defers default-command details to `<bin> --help`-style hints.
25
+ *
26
+ * @defaultValue `true`
27
+ */
28
+ readonly inlineDefault?: boolean;
29
+ /**
30
+ * List the default command in the root `Commands:` table.
31
+ *
32
+ * By default the default command is treated as the root surface and omitted
33
+ * from the command list (its args/flags render inline instead).
34
+ *
35
+ * @defaultValue `false`
36
+ */
37
+ readonly showDefaultInCommands?: boolean;
38
+ /**
39
+ * Show the `Run '<bin> <command> --help' for more information.` footer.
40
+ *
41
+ * Defaults to showing the hint only when visible subcommands exist; set
42
+ * explicitly to force it on or off.
43
+ */
44
+ readonly footer?: boolean;
18
45
  /** @internal Whether this usage line is being rendered as merged root/default help. */
19
46
  readonly isDefaultHelp?: boolean;
47
+ /**
48
+ * Gated ANSI palette used to style help output. Identity formatters mean
49
+ * plain text. `CLIBuilder.execute()`/`.run()` thread the output channel's
50
+ * `out.color` here automatically, so styling follows the same policy as
51
+ * handler output (TTY + color support, no `--json`, `NO_COLOR` honored).
52
+ *
53
+ * @defaultValue `undefined` (plain text)
54
+ */
55
+ readonly colors?: Colors;
56
+ /**
57
+ * Theme overrides merged over the built-in help theme. Receives the gated
58
+ * palette; never invoked when color is off, so overrides cannot leak
59
+ * escapes into piped output.
60
+ *
61
+ * @defaultValue `undefined` (built-in theme)
62
+ */
63
+ readonly theme?: HelpThemeFactory;
64
+ }
65
+ /** Formatted flag entry for the flags table. @internal */
66
+ interface FlagEntry {
67
+ readonly left: string;
68
+ readonly description: string;
20
69
  }
21
70
  /**
22
71
  * Build the ordered help sections without joining them.
@@ -53,5 +102,19 @@ declare function formatHelpSections(schema: CommandSchema, options?: HelpOptions
53
102
  * ```
54
103
  */
55
104
  declare function formatHelp(schema: CommandSchema, options?: HelpOptions): string;
105
+ /**
106
+ * Render a titled two-column flag block from pre-built {@link FlagEntry} rows.
107
+ *
108
+ * Shared by the per-command `Flags:` section and the root-help `Global options:`
109
+ * block (built-in flags), so column alignment and description wrapping stay
110
+ * identical across both. Returns `''` when there are no entries.
111
+ *
112
+ * @param title - Section heading (e.g. `'Flags:'`, `'Global options:'`), pre-styled by the caller.
113
+ * @param entries - Formatted left/description rows.
114
+ * @param width - Terminal width for description wrapping.
115
+ * @returns Multi-line block string, or `''` when `entries` is empty.
116
+ * @internal
117
+ */
118
+ declare function formatFlagEntriesBlock(title: string, entries: readonly FlagEntry[], width: number): string;
56
119
  //#endregion
57
- export { type HelpOptions, formatHelp, formatHelpSections, osc8, visibleWidth };
120
+ export { type FlagEntry, type HelpOptions, type HelpTheme, type HelpThemeFactory, formatFlagEntriesBlock, formatHelp, formatHelpSections, osc8, visibleWidth };