@kjanat/dreamcli 4.0.0-rc.3 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (212) hide show
  1. package/README.md +5 -7
  2. package/dist/{runtime/adapter.d.mts → adapter-D0hbBNVB.d.mts} +2 -4
  3. package/dist/completion-D4mz6axB.mjs +6 -0
  4. package/dist/completion.d.mts +90 -0
  5. package/dist/completion.mjs +1 -0
  6. package/dist/config-B9ddC-Kb.mjs +1 -0
  7. package/dist/config.d.mts +2 -0
  8. package/dist/config.mjs +1 -0
  9. package/dist/core-Cp2w8vRq.mjs +17 -0
  10. package/dist/index-BziI2aKc.d.mts +5440 -0
  11. package/dist/index-DOfClfYR.d.mts +370 -0
  12. package/dist/index-DWsnGZlx.d.mts +831 -0
  13. package/dist/{core/cli/index.d.mts → index-DXROeDPC.d.mts} +116 -57
  14. package/dist/index-DndPmT8J.d.mts +275 -0
  15. package/dist/{core/json-schema/index.d.mts → index-DyoaS234.d.mts} +43 -34
  16. package/dist/index.d.mts +190 -41
  17. package/dist/index.mjs +1 -26
  18. package/dist/json-schema-C9SzZ7jY.mjs +52 -0
  19. package/dist/json-schema.d.mts +2 -0
  20. package/dist/json-schema.mjs +1 -0
  21. package/dist/package-json-BgE9YjjQ.mjs +3 -0
  22. package/dist/prompt.d.mts +48 -0
  23. package/dist/prompt.mjs +1 -0
  24. package/dist/rolldown-runtime-G4Kt5YOX.mjs +1 -0
  25. package/dist/runtime.d.mts +2 -6
  26. package/dist/runtime.mjs +1 -6
  27. package/dist/terminal-C8KTXjv5.mjs +6 -0
  28. package/dist/test-prompter-v__jT2yG.mjs +1 -0
  29. package/dist/testkit.d.mts +54 -6
  30. package/dist/testkit.mjs +1 -5
  31. package/dist/version.mjs +1 -7
  32. package/dreamcli.schema.json +697 -538
  33. package/package.json +29 -7
  34. package/skills/cli-creation/SKILL.md +16 -11
  35. package/CHANGELOG.md +0 -1116
  36. package/dist/core/cli/builtins.d.mts +0 -117
  37. package/dist/core/cli/builtins.mjs +0 -135
  38. package/dist/core/cli/compiled.d.mts +0 -66
  39. package/dist/core/cli/compiled.mjs +0 -76
  40. package/dist/core/cli/dispatch.d.mts +0 -115
  41. package/dist/core/cli/dispatch.mjs +0 -205
  42. package/dist/core/cli/help-links.d.mts +0 -27
  43. package/dist/core/cli/help-links.mjs +0 -41
  44. package/dist/core/cli/index.mjs +0 -1271
  45. package/dist/core/cli/planner.d.mts +0 -174
  46. package/dist/core/cli/planner.mjs +0 -323
  47. package/dist/core/cli/plugin.d.mts +0 -94
  48. package/dist/core/cli/plugin.mjs +0 -41
  49. package/dist/core/cli/propagate.d.mts +0 -39
  50. package/dist/core/cli/propagate.mjs +0 -57
  51. package/dist/core/cli/reserved-flags.d.mts +0 -19
  52. package/dist/core/cli/reserved-flags.mjs +0 -158
  53. package/dist/core/cli/root-help.d.mts +0 -53
  54. package/dist/core/cli/root-help.mjs +0 -221
  55. package/dist/core/cli/root-output-flags.d.mts +0 -74
  56. package/dist/core/cli/root-output-flags.mjs +0 -169
  57. package/dist/core/cli/root-surface.d.mts +0 -64
  58. package/dist/core/cli/root-surface.mjs +0 -28
  59. package/dist/core/cli/runtime-preflight.d.mts +0 -213
  60. package/dist/core/cli/runtime-preflight.mjs +0 -221
  61. package/dist/core/completion/index.d.mts +0 -76
  62. package/dist/core/completion/index.mjs +0 -90
  63. package/dist/core/completion/shells/bash.d.mts +0 -23
  64. package/dist/core/completion/shells/bash.mjs +0 -312
  65. package/dist/core/completion/shells/fish.d.mts +0 -19
  66. package/dist/core/completion/shells/fish.mjs +0 -164
  67. package/dist/core/completion/shells/powershell.d.mts +0 -13
  68. package/dist/core/completion/shells/powershell.mjs +0 -360
  69. package/dist/core/completion/shells/shared.d.mts +0 -164
  70. package/dist/core/completion/shells/shared.mjs +0 -147
  71. package/dist/core/completion/shells/zsh.d.mts +0 -23
  72. package/dist/core/completion/shells/zsh.mjs +0 -256
  73. package/dist/core/config/index.d.mts +0 -191
  74. package/dist/core/config/index.mjs +0 -285
  75. package/dist/core/config/package-json.d.mts +0 -179
  76. package/dist/core/config/package-json.mjs +0 -353
  77. package/dist/core/errors/index.d.mts +0 -125
  78. package/dist/core/errors/index.mjs +0 -87
  79. package/dist/core/execution/index.d.mts +0 -61
  80. package/dist/core/execution/index.mjs +0 -220
  81. package/dist/core/help/ansi.d.mts +0 -84
  82. package/dist/core/help/ansi.mjs +0 -121
  83. package/dist/core/help/index.d.mts +0 -149
  84. package/dist/core/help/index.mjs +0 -418
  85. package/dist/core/help/theme.d.mts +0 -86
  86. package/dist/core/help/theme.mjs +0 -69
  87. package/dist/core/json-schema/index.mjs +0 -1008
  88. package/dist/core/json-schema/meta-descriptions.generated.d.mts +0 -274
  89. package/dist/core/json-schema/meta-descriptions.generated.mjs +0 -136
  90. package/dist/core/output/activity.d.mts +0 -193
  91. package/dist/core/output/activity.mjs +0 -452
  92. package/dist/core/output/bind.d.mts +0 -37
  93. package/dist/core/output/bind.mjs +0 -56
  94. package/dist/core/output/contracts.d.mts +0 -82
  95. package/dist/core/output/contracts.mjs +0 -57
  96. package/dist/core/output/display-value.d.mts +0 -19
  97. package/dist/core/output/display-value.mjs +0 -32
  98. package/dist/core/output/index.d.mts +0 -344
  99. package/dist/core/output/index.mjs +0 -514
  100. package/dist/core/output/renderers.d.mts +0 -45
  101. package/dist/core/output/renderers.mjs +0 -46
  102. package/dist/core/output/writer.d.mts +0 -39
  103. package/dist/core/output/writer.mjs +0 -12
  104. package/dist/core/parse/index.d.mts +0 -178
  105. package/dist/core/parse/index.mjs +0 -850
  106. package/dist/core/parse/occurrences.d.mts +0 -90
  107. package/dist/core/parse/occurrences.mjs +0 -114
  108. package/dist/core/prompt/index.d.mts +0 -213
  109. package/dist/core/prompt/index.mjs +0 -348
  110. package/dist/core/read-flags/index.d.mts +0 -150
  111. package/dist/core/read-flags/index.mjs +0 -217
  112. package/dist/core/resolve/args.d.mts +0 -39
  113. package/dist/core/resolve/args.mjs +0 -182
  114. package/dist/core/resolve/coerce.d.mts +0 -79
  115. package/dist/core/resolve/coerce.mjs +0 -900
  116. package/dist/core/resolve/config.d.mts +0 -10
  117. package/dist/core/resolve/config.mjs +0 -19
  118. package/dist/core/resolve/contracts.d.mts +0 -146
  119. package/dist/core/resolve/errors.d.mts +0 -10
  120. package/dist/core/resolve/errors.mjs +0 -148
  121. package/dist/core/resolve/flags.d.mts +0 -74
  122. package/dist/core/resolve/flags.mjs +0 -246
  123. package/dist/core/resolve/index.d.mts +0 -44
  124. package/dist/core/resolve/index.mjs +0 -123
  125. package/dist/core/resolve/path-checks.d.mts +0 -48
  126. package/dist/core/resolve/path-checks.mjs +0 -102
  127. package/dist/core/resolve/redaction.d.mts +0 -13
  128. package/dist/core/resolve/redaction.mjs +0 -14
  129. package/dist/core/resolve/stages.d.mts +0 -86
  130. package/dist/core/resolve/stages.mjs +0 -170
  131. package/dist/core/resolve/standard.d.mts +0 -26
  132. package/dist/core/resolve/standard.mjs +0 -212
  133. package/dist/core/schema/activity.d.mts +0 -189
  134. package/dist/core/schema/arg.d.mts +0 -1461
  135. package/dist/core/schema/arg.mjs +0 -1139
  136. package/dist/core/schema/brand.d.mts +0 -17
  137. package/dist/core/schema/cardinality.d.mts +0 -302
  138. package/dist/core/schema/cardinality.mjs +0 -514
  139. package/dist/core/schema/command.d.mts +0 -1132
  140. package/dist/core/schema/command.mjs +0 -999
  141. package/dist/core/schema/flag.d.mts +0 -1495
  142. package/dist/core/schema/flag.mjs +0 -1207
  143. package/dist/core/schema/index.d.mts +0 -15
  144. package/dist/core/schema/index.mjs +0 -10
  145. package/dist/core/schema/middleware.d.mts +0 -129
  146. package/dist/core/schema/middleware.mjs +0 -41
  147. package/dist/core/schema/number-constraints.d.mts +0 -96
  148. package/dist/core/schema/number-constraints.mjs +0 -60
  149. package/dist/core/schema/prompt.d.mts +0 -135
  150. package/dist/core/schema/provenance.d.mts +0 -99
  151. package/dist/core/schema/provenance.mjs +0 -28
  152. package/dist/core/schema/run.d.mts +0 -211
  153. package/dist/core/schema/source.d.mts +0 -180
  154. package/dist/core/schema/source.mjs +0 -206
  155. package/dist/core/schema/standard.d.mts +0 -100
  156. package/dist/core/schema/standard.mjs +0 -15
  157. package/dist/core/schema/stdin.d.mts +0 -97
  158. package/dist/core/schema/stdin.mjs +0 -91
  159. package/dist/core/schema/string-constraints.d.mts +0 -108
  160. package/dist/core/schema/string-constraints.mjs +0 -86
  161. package/dist/core/schema/value-parsers.d.mts +0 -150
  162. package/dist/core/schema/value-parsers.mjs +0 -160
  163. package/dist/core/schema/value.d.mts +0 -243
  164. package/dist/core/schema/value.mjs +0 -573
  165. package/dist/core/testkit/index.d.mts +0 -63
  166. package/dist/core/testkit/index.mjs +0 -102
  167. package/dist/runtime/adapter.mjs +0 -92
  168. package/dist/runtime/auto.d.mts +0 -25
  169. package/dist/runtime/auto.mjs +0 -45
  170. package/dist/runtime/deno.d.mts +0 -99
  171. package/dist/runtime/deno.mjs +0 -265
  172. package/dist/runtime/detect.d.mts +0 -86
  173. package/dist/runtime/detect.mjs +0 -45
  174. package/dist/runtime/index.d.mts +0 -6
  175. package/dist/runtime/node.d.mts +0 -71
  176. package/dist/runtime/node.mjs +0 -228
  177. package/dist/runtime/paths.d.mts +0 -31
  178. package/dist/runtime/paths.mjs +0 -48
  179. package/dist/strings.d.mts +0 -27
  180. package/dist/strings.mjs +0 -22
  181. package/examples/basic.ts +0 -37
  182. package/examples/flag-types.ts +0 -79
  183. package/examples/gh/package.json +0 -45
  184. package/examples/gh/src/commands/auth.ts +0 -66
  185. package/examples/gh/src/commands/issue.ts +0 -120
  186. package/examples/gh/src/commands/pr.ts +0 -125
  187. package/examples/gh/src/data/issues.yaml +0 -5
  188. package/examples/gh/src/data/issues.yaml.d.ts +0 -17
  189. package/examples/gh/src/data/pull-requests.yaml +0 -7
  190. package/examples/gh/src/data/pull-requests.yaml.d.ts +0 -18
  191. package/examples/gh/src/docs.ts +0 -11
  192. package/examples/gh/src/lib/auth.ts +0 -37
  193. package/examples/gh/src/lib/utils.ts +0 -17
  194. package/examples/gh/src/main.test.ts +0 -307
  195. package/examples/gh/src/main.ts +0 -46
  196. package/examples/help-config.ts +0 -43
  197. package/examples/interactive.ts +0 -67
  198. package/examples/json-mode.ts +0 -95
  199. package/examples/middleware.ts +0 -71
  200. package/examples/multi-command.ts +0 -66
  201. package/examples/output-extras.ts +0 -46
  202. package/examples/parser-control.ts +0 -40
  203. package/examples/pwsh-demo/README.md +0 -40
  204. package/examples/pwsh-demo/package.json +0 -41
  205. package/examples/pwsh-demo/pwsh-demo.cmd +0 -3
  206. package/examples/pwsh-demo/smoke-powershell.ps1 +0 -218
  207. package/examples/pwsh-demo/src/main.test.ts +0 -45
  208. package/examples/pwsh-demo/src/main.ts +0 -140
  209. package/examples/spinner-progress.ts +0 -49
  210. package/examples/standard-schema.ts +0 -45
  211. package/examples/testing.ts +0 -147
  212. package/examples/transport-launcher.ts +0 -85
@@ -1,220 +0,0 @@
1
- import { CLIError } from "../errors/index.mjs";
2
- import { parse, requestsHelp } from "../parse/index.mjs";
3
- import { builtinEnabled } from "../cli/builtins.mjs";
4
- import { formatHelp } from "../help/index.mjs";
5
- import { generateCommandSchema } from "../json-schema/index.mjs";
6
- import { clearRequestedExitCode, getRequestedExitCode } from "../output/index.mjs";
7
- import { createTestPrompter } from "../prompt/index.mjs";
8
- import { resolve } from "../resolve/index.mjs";
9
- //#region src/core/execution/index.ts
10
- /**
11
- * Shared command execution seam.
12
- *
13
- * Centralizes the parse -> resolve -> plugin -> handler pipeline so CLI and
14
- * testkit can converge on one owned execution path during the re-foundation.
15
- *
16
- * @module dreamcli/core/execution
17
- * @internal
18
- */
19
- /**
20
- * Run the full parse -> resolve -> plugin -> handler pipeline for one command.
21
- *
22
- * Handles `--help` short-circuit, plugin lifecycle hooks, deprecation warnings,
23
- * and error wrapping. Both CLI dispatch and testkit `runCommand` converge here.
24
- * @internal
25
- */
26
- async function executeCommand(request) {
27
- const { argv, command, meta, options, out, schema } = request;
28
- clearRequestedExitCode(out);
29
- try {
30
- if (builtinEnabled(options?.builtins, "help") && requestsHelp(argv)) {
31
- if (out.jsonMode || options?.jsonMode === true) {
32
- out.json(generateCommandSchema(schema, void 0, {
33
- name: options?.help?.binName ?? schema.name,
34
- version: options?.help?.version
35
- }));
36
- return {
37
- exitCode: 0,
38
- error: void 0
39
- };
40
- }
41
- const helpText = formatHelp(schema, options?.help?.colors !== void 0 ? options.help : {
42
- ...options?.help,
43
- colors: out.color
44
- });
45
- out.log(helpText);
46
- return {
47
- exitCode: 0,
48
- error: void 0
49
- };
50
- }
51
- const handler = command.handler;
52
- if (handler === void 0) {
53
- const error = new CLIError(`Command '${schema.name}' has no action handler`, {
54
- code: "NO_ACTION",
55
- suggest: `Add an .action() handler to the '${schema.name}' command`
56
- });
57
- out.error(error.message);
58
- return {
59
- exitCode: 1,
60
- error
61
- };
62
- }
63
- await runBeforeParseHooks(options?.plugins, {
64
- argv,
65
- command: schema,
66
- meta,
67
- out
68
- });
69
- const parsed = parse(schema, argv, options?.flags);
70
- const effectivePrompter = options?.prompter ?? (options?.answers !== void 0 ? createTestPrompter(options.answers) : void 0);
71
- const resolveOptions = {
72
- ...options?.stdinData !== void 0 ? { stdinData: options.stdinData } : {},
73
- ...options?.env !== void 0 ? { env: options.env } : {},
74
- ...options?.config !== void 0 ? { config: options.config } : {},
75
- ...effectivePrompter !== void 0 ? { prompter: effectivePrompter } : {},
76
- ...options?.stat !== void 0 ? { stat: options.stat } : {},
77
- ...options?.mkdir !== void 0 ? { mkdir: options.mkdir } : {}
78
- };
79
- const resolved = await resolve(schema, parsed, resolveOptions);
80
- const resolvedParams = {
81
- args: resolved.args,
82
- flags: resolved.flags,
83
- deprecations: resolved.deprecations,
84
- command: schema,
85
- meta,
86
- out
87
- };
88
- await runResolvedHooks(options?.plugins, "afterResolve", resolvedParams);
89
- for (const deprecation of resolved.deprecations) out.warn(formatDeprecation(deprecation));
90
- await runResolvedHooks(options?.plugins, "beforeAction", resolvedParams);
91
- await executeWithExecutionSteps(command, handler, resolved, out, meta);
92
- await runResolvedHooks(options?.plugins, "afterAction", resolvedParams);
93
- return {
94
- exitCode: getRequestedExitCode(out) ?? 0,
95
- error: void 0
96
- };
97
- } catch (error) {
98
- if (error instanceof CLIError) {
99
- if (options?.jsonMode === true) out.json({ error: error.toJSON() });
100
- else {
101
- out.error(error.message);
102
- if (error.suggest !== void 0) out.error(`Suggestion: ${error.suggest}`);
103
- }
104
- return {
105
- exitCode: error.exitCode,
106
- error
107
- };
108
- }
109
- const message = error instanceof Error ? error.message : String(error);
110
- const wrapped = new CLIError(`Unexpected error: ${message}`, {
111
- code: "UNEXPECTED_ERROR",
112
- cause: error
113
- });
114
- if (options?.jsonMode === true) out.json({ error: wrapped.toJSON() });
115
- else out.error(wrapped.message);
116
- return {
117
- exitCode: 1,
118
- error: wrapped
119
- };
120
- } finally {
121
- out.stopActive();
122
- clearRequestedExitCode(out);
123
- }
124
- }
125
- async function runBeforeParseHooks(plugins, params) {
126
- if (plugins === void 0) return;
127
- for (const current of plugins) {
128
- const hook = current.hooks.beforeParse;
129
- if (hook !== void 0) await hook(params);
130
- }
131
- }
132
- async function runResolvedHooks(plugins, hookName, params) {
133
- if (plugins === void 0) return;
134
- for (const current of plugins) {
135
- const hook = current.hooks[hookName];
136
- if (hook !== void 0) await hook(params);
137
- }
138
- }
139
- async function executeWithExecutionSteps(command, handler, resolved, out, meta) {
140
- const steps = command.steps;
141
- const { args, flags } = resolved;
142
- const sources = resolved.provenance;
143
- let chain = async (ctx) => {
144
- await handler({
145
- flags,
146
- args,
147
- sources,
148
- ctx,
149
- out,
150
- meta
151
- });
152
- };
153
- for (let i = steps.length - 1; i >= 0; i--) {
154
- const step = steps[i];
155
- if (step === void 0) continue;
156
- const downstream = chain;
157
- switch (step.kind) {
158
- case "derive":
159
- chain = async (ctx) => {
160
- const additions = await step.handler({
161
- args,
162
- flags,
163
- sources,
164
- ctx,
165
- out,
166
- meta
167
- });
168
- if (additions === void 0) {
169
- await downstream(ctx);
170
- return;
171
- }
172
- if (typeof additions !== "object" || additions === null || Array.isArray(additions)) throw new CLIError("derive() must return an object or undefined", {
173
- code: "INVALID_BUILDER_STATE",
174
- suggest: "Return an object to add context, or return nothing for validation-only derive handlers"
175
- });
176
- await downstream({
177
- ...ctx,
178
- ...additions
179
- });
180
- };
181
- break;
182
- case "middleware": chain = async (ctx) => {
183
- await step.handler({
184
- args,
185
- flags,
186
- sources,
187
- ctx,
188
- out,
189
- meta,
190
- next: async (additions) => {
191
- await downstream({
192
- ...ctx,
193
- ...additions
194
- });
195
- }
196
- });
197
- };
198
- }
199
- }
200
- await chain({});
201
- }
202
- /**
203
- * Assemble a {@linkcode CommandExecutionResult} and captured output buffers into a public `RunResult`.
204
- * @internal
205
- */
206
- function buildRunResult(result, captured) {
207
- return {
208
- exitCode: result.exitCode,
209
- stdout: captured.stdout,
210
- stderr: captured.stderr,
211
- activity: captured.activity,
212
- error: result.error
213
- };
214
- }
215
- function formatDeprecation(deprecation) {
216
- const entity = deprecation.kind === "flag" ? `flag --${deprecation.name}` : `argument <${deprecation.name}>`;
217
- return typeof deprecation.message === "string" ? `Warning: ${entity} is deprecated: ${deprecation.message}` : `Warning: ${entity} is deprecated`;
218
- }
219
- //#endregion
220
- export { buildRunResult, executeCommand };
@@ -1,84 +0,0 @@
1
- //#region src/core/help/ansi.d.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
- * Remove ANSI CSI and OSC escape sequences from `text`.
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
- *
21
- * @param text - Text possibly containing terminal escapes.
22
- * @returns The text with all escape sequences removed.
23
- */
24
- declare function stripAnsi(text: string): string;
25
- /**
26
- * Measure the visible column width of `text`, ignoring ANSI/OSC escapes.
27
- *
28
- * Escape sequences (SGR colors, OSC 8 hyperlinks) occupy zero columns when
29
- * rendered, so `.length` overcounts whenever they are present. Help
30
- * formatting uses this for padding and wrapping; exported for custom help
31
- * renderers that mix colors or links into aligned output.
32
- *
33
- * @param text - Text possibly containing terminal escapes.
34
- * @returns Number of visible characters.
35
- *
36
- * @example
37
- * ```ts
38
- * visibleWidth('plain'); // 5
39
- * visibleWidth(osc8('https://x.dev', 'x')); // 1
40
- * ```
41
- */
42
- declare function visibleWidth(text: string): number;
43
- /**
44
- * Wrap `text` in an [OSC 8 hyperlink](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda)
45
- * pointing at `url`.
46
- *
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.
51
- *
52
- * @param url - Link target (string or `URL` instance).
53
- * @param text - Visible link text.
54
- * @returns The OSC 8 escape sequence wrapping `text`.
55
- *
56
- * @example
57
- * ```ts
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
60
- * ```
61
- */
62
- declare function osc8(url: string | URL, text?: string): string;
63
- /**
64
- * Pad `text` to `length` visible columns with trailing spaces.
65
- *
66
- * @param text - The string to pad (may contain ANSI/OSC escapes).
67
- * @param length - Target visible width in columns.
68
- * @returns The padded string, unchanged if already at or beyond `length`.
69
- */
70
- declare function padEnd(text: string, length: number): string;
71
- /**
72
- * Wrap text to `width`, preserving leading indent on continuation lines.
73
- *
74
- * Line lengths are measured with {@linkcode visibleWidth}, so embedded
75
- * ANSI/OSC escapes do not trigger premature wrapping.
76
- *
77
- * @param text - The text to wrap.
78
- * @param width - Maximum line width in columns.
79
- * @param indent - Number of leading spaces for continuation lines.
80
- * @returns The wrapped string with newlines inserted as needed.
81
- */
82
- declare function wrapText(text: string, width: number, indent: number): string;
83
- //#endregion
84
- export { osc8, padEnd, stripAnsi, visibleWidth, wrapText };
@@ -1,121 +0,0 @@
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,149 +0,0 @@
1
- import { HelpDescription, HelpTheme, HelpThemeFactory } from "./theme.mjs";
2
- import { CommandSchema } from "../schema/command.mjs";
3
- import { osc8, visibleWidth } from "./ansi.mjs";
4
- import "../schema/index.mjs";
5
- import { Colors } from "ansispeck";
6
- //#region src/core/help/index.d.ts
7
- /** Options for customising help output. */
8
- interface HelpOptions {
9
- /** Maximum line width (columns). Defaults to 80. */
10
- readonly width?: number;
11
- /** Binary/program name shown in the usage line. Defaults to command name. */
12
- readonly binName?: string;
13
- /** Program version passed to function-form examples as `meta.version`. */
14
- readonly version?: string;
15
- /**
16
- * Order of flags in the `Flags:` table.
17
- *
18
- * - `'alphabetical'` — short-aliased flags first, then alphabetical by name.
19
- * - `'declaration'` — the order `.flag()` was called.
20
- *
21
- * Ignored when {@link HelpOptions.sortFlags} is set.
22
- *
23
- * @defaultValue `'alphabetical'`
24
- */
25
- readonly flagOrder?: 'alphabetical' | 'declaration';
26
- /**
27
- * Custom comparator over flag long names for the `Flags:` table. When set,
28
- * it wins over {@link HelpOptions.flagOrder}.
29
- *
30
- * @defaultValue `undefined` (use `flagOrder`)
31
- */
32
- readonly sortFlags?: (a: string, b: string) => number;
33
- /**
34
- * Emit OSC 8 hyperlinks where link metadata is available (currently the
35
- * root-help header name/version configured via `CLIBuilder.links()`).
36
- * Defaults to `false`; `CLIBuilder.execute()`/`.run()` enable it
37
- * automatically when stdout is a TTY.
38
- */
39
- readonly hyperlinks?: boolean;
40
- /**
41
- * Render the default command's arguments and flags inline in root help.
42
- *
43
- * Only affects root-level help. When `false`, root help lists commands and
44
- * defers default-command details to `<bin> --help`-style hints.
45
- *
46
- * @defaultValue `true`
47
- */
48
- readonly inlineDefault?: boolean;
49
- /**
50
- * List the default command in the root `Commands:` table.
51
- *
52
- * By default the default command is treated as the root surface and omitted
53
- * from the command list (its args/flags render inline instead).
54
- *
55
- * @defaultValue `false`
56
- */
57
- readonly showDefaultInCommands?: boolean;
58
- /**
59
- * Show the `Run '<bin> <command> --help' for more information.` footer.
60
- *
61
- * Defaults to showing the hint only when visible subcommands exist; set
62
- * explicitly to force it on or off.
63
- */
64
- readonly footer?: boolean;
65
- /** @internal Whether this usage line is being rendered as merged root/default help. */
66
- readonly isDefaultHelp?: boolean;
67
- /**
68
- * Gated ANSI palette used to style help output. Identity formatters mean
69
- * plain text. `CLIBuilder.execute()`/`.run()` thread the output channel's
70
- * `out.color` here automatically, so styling follows the same policy as
71
- * handler output (TTY + color support, no `--json`, `NO_COLOR` honored).
72
- *
73
- * @defaultValue `undefined` (plain text)
74
- */
75
- readonly colors?: Colors;
76
- /**
77
- * Theme overrides merged over the built-in help theme. Receives the gated
78
- * palette; never invoked when color is off, so overrides cannot leak
79
- * escapes into piped output.
80
- *
81
- * @defaultValue `undefined` (built-in theme)
82
- */
83
- readonly theme?: HelpThemeFactory;
84
- /**
85
- * Theme overrides used only by function-form flag and argument descriptions.
86
- * Merged over the resolved global theme, one role at a time.
87
- *
88
- * @defaultValue `undefined` (use the global theme)
89
- */
90
- readonly descriptionTheme?: HelpThemeFactory;
91
- }
92
- /** Formatted flag entry for the flags table. @internal */
93
- interface FlagEntry {
94
- /** Preformatted flag names and value hint for the left table column. */
95
- readonly left: string;
96
- /** Preformatted help text for the description table column. */
97
- readonly description: string;
98
- }
99
- /**
100
- * Build the ordered help sections without joining them.
101
- *
102
- * @internal
103
- * @param schema - The {@link CommandSchema} to render.
104
- * @param options - Optional {@link HelpOptions} for width/bin name.
105
- * @returns Array of section strings (usage, description, commands, args, flags, examples).
106
- */
107
- declare function formatHelpSections(schema: CommandSchema, options?: HelpOptions): readonly string[];
108
- /**
109
- * Generate help text from a command schema.
110
- *
111
- * Low-level formatter: most applications reach this through `--help`,
112
- * `help <command>`, or root help rendering in `CLIBuilder`. Call
113
- * `formatHelp()` directly when embedding DreamCLI help text into custom UIs,
114
- * tests, or generated docs.
115
- *
116
- * Sections rendered (in order):
117
- * 1. **Usage** line — `program <command> [flags] <args>`
118
- * 2. **Description** — the command's `.description()` text
119
- * 3. **Commands** — subcommands table (if any, skips hidden)
120
- * 4. **Arguments** — positional args table (if any)
121
- * 5. **Flags** — flags table with type hints and defaults
122
- * 6. **Examples** — usage examples (if any)
123
- *
124
- * @param schema - The command schema to render help for.
125
- * @param options - Formatting options (width, binary name).
126
- * @returns The formatted help string.
127
- *
128
- * @example
129
- * ```ts
130
- * const text = formatHelp(deploy.schema, { binName: 'mycli' });
131
- * ```
132
- */
133
- declare function formatHelp(schema: CommandSchema, options?: HelpOptions): string;
134
- /**
135
- * Render a titled two-column flag block from pre-built {@link FlagEntry} rows.
136
- *
137
- * Shared by the per-command `Flags:` section and the root-help `Global options:`
138
- * block (built-in flags), so column alignment and description wrapping stay
139
- * identical across both. Returns `''` when there are no entries.
140
- *
141
- * @param title - Section heading (e.g. `'Flags:'`, `'Global options:'`), pre-styled by the caller.
142
- * @param entries - Formatted left/description rows.
143
- * @param width - Terminal width for description wrapping.
144
- * @returns Multi-line block string, or `''` when `entries` is empty.
145
- * @internal
146
- */
147
- declare function formatFlagEntriesBlock(title: string, entries: readonly FlagEntry[], width: number): string;
148
- //#endregion
149
- export { type FlagEntry, type HelpDescription, type HelpOptions, type HelpTheme, type HelpThemeFactory, formatFlagEntriesBlock, formatHelp, formatHelpSections, osc8, visibleWidth };