@kjanat/dreamcli 2.5.0 → 3.0.0-rc.2

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 (160) hide show
  1. package/CHANGELOG.md +153 -1
  2. package/README.md +9 -2
  3. package/dist/core/cli/dispatch.mjs +214 -1
  4. package/dist/core/cli/help-links.mjs +41 -1
  5. package/dist/core/cli/index.d.mts +109 -16
  6. package/dist/core/cli/index.mjs +901 -1
  7. package/dist/core/cli/planner.d.mts +27 -5
  8. package/dist/core/cli/planner.mjs +300 -1
  9. package/dist/core/cli/plugin.mjs +41 -1
  10. package/dist/core/cli/propagate.mjs +57 -1
  11. package/dist/core/cli/root-help.d.mts +16 -2
  12. package/dist/core/cli/root-help.mjs +208 -6
  13. package/dist/core/cli/root-surface.d.mts +18 -3
  14. package/dist/core/cli/root-surface.mjs +27 -1
  15. package/dist/core/cli/runtime-preflight.d.mts +16 -1
  16. package/dist/core/cli/runtime-preflight.mjs +168 -1
  17. package/dist/core/completion/index.d.mts +32 -1
  18. package/dist/core/completion/index.mjs +90 -1
  19. package/dist/core/completion/shells/bash.mjs +304 -3
  20. package/dist/core/completion/shells/fish.mjs +159 -2
  21. package/dist/core/completion/shells/powershell.mjs +353 -2
  22. package/dist/core/completion/shells/shared.d.mts +10 -0
  23. package/dist/core/completion/shells/shared.mjs +154 -1
  24. package/dist/core/completion/shells/zsh.mjs +244 -2
  25. package/dist/core/config/index.mjs +246 -1
  26. package/dist/core/config/package-json.mjs +385 -3
  27. package/dist/core/errors/index.mjs +87 -1
  28. package/dist/core/execution/index.mjs +189 -1
  29. package/dist/core/help/ansi.mjs +122 -2
  30. package/dist/core/help/index.d.mts +45 -1
  31. package/dist/core/help/index.mjs +329 -7
  32. package/dist/core/json-schema/index.mjs +487 -9
  33. package/dist/core/json-schema/meta-descriptions.generated.d.mts +38 -38
  34. package/dist/core/json-schema/meta-descriptions.generated.mjs +93 -28
  35. package/dist/core/output/activity.mjs +452 -1
  36. package/dist/core/output/bind.mjs +56 -1
  37. package/dist/core/output/contracts.mjs +57 -1
  38. package/dist/core/output/display-value.mjs +32 -1
  39. package/dist/core/output/index.d.mts +21 -0
  40. package/dist/core/output/index.mjs +442 -2
  41. package/dist/core/output/renderers.mjs +46 -1
  42. package/dist/core/output/writer.mjs +12 -1
  43. package/dist/core/parse/index.d.mts +15 -1
  44. package/dist/core/parse/index.mjs +555 -1
  45. package/dist/core/prompt/index.d.mts +11 -4
  46. package/dist/core/prompt/index.mjs +348 -6
  47. package/dist/core/resolve/args.mjs +105 -1
  48. package/dist/core/resolve/coerce.mjs +279 -1
  49. package/dist/core/resolve/config.mjs +19 -1
  50. package/dist/core/resolve/errors.mjs +140 -2
  51. package/dist/core/resolve/flags.mjs +196 -1
  52. package/dist/core/resolve/index.mjs +85 -1
  53. package/dist/core/resolve/property.d.mts +2 -1
  54. package/dist/core/resolve/property.mjs +45 -1
  55. package/dist/core/schema/arg.d.mts +90 -10
  56. package/dist/core/schema/arg.mjs +463 -1
  57. package/dist/core/schema/command.d.mts +21 -1
  58. package/dist/core/schema/command.mjs +712 -1
  59. package/dist/core/schema/flag.d.mts +92 -2
  60. package/dist/core/schema/flag.mjs +453 -1
  61. package/dist/core/schema/index.d.mts +2 -1
  62. package/dist/core/schema/middleware.mjs +41 -1
  63. package/dist/core/schema/number-constraints.d.mts +96 -0
  64. package/dist/core/schema/number-constraints.mjs +60 -0
  65. package/dist/core/schema/prompt.d.mts +15 -0
  66. package/dist/core/schema/run.d.mts +4 -4
  67. package/dist/core/schema-dsl/runtime.mjs +271 -2
  68. package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
  69. package/dist/core/testkit/index.d.mts +9 -5
  70. package/dist/core/testkit/index.mjs +83 -1
  71. package/dist/index.d.mts +3 -1
  72. package/dist/index.mjs +22 -1
  73. package/dist/runtime/adapter.mjs +82 -1
  74. package/dist/runtime/auto.mjs +46 -1
  75. package/dist/runtime/bun.mjs +28 -1
  76. package/dist/runtime/deno.mjs +217 -2
  77. package/dist/runtime/detect.mjs +45 -1
  78. package/dist/runtime/node.mjs +169 -2
  79. package/dist/runtime/paths.mjs +48 -1
  80. package/dist/runtime.mjs +7 -1
  81. package/dist/strings.mjs +22 -1
  82. package/dist/testkit.mjs +5 -1
  83. package/dist/version.mjs +7 -1
  84. package/examples/basic.ts +5 -1
  85. package/examples/gh/package.json +2 -7
  86. package/examples/pwsh-demo/package.json +1 -7
  87. package/examples/pwsh-demo/src/main.test.ts +1 -4
  88. package/examples/pwsh-demo/src/main.ts +14 -4
  89. package/examples/transport-launcher.ts +85 -0
  90. package/package.json +23 -41
  91. package/dist/runtime/support.d.mts +0 -42
  92. package/dist/runtime/support.mjs +0 -1
  93. package/src/core/cli/dispatch.ts +0 -349
  94. package/src/core/cli/help-links.ts +0 -82
  95. package/src/core/cli/index.ts +0 -1413
  96. package/src/core/cli/planner.ts +0 -487
  97. package/src/core/cli/plugin.ts +0 -117
  98. package/src/core/cli/propagate.ts +0 -97
  99. package/src/core/cli/root-help.ts +0 -252
  100. package/src/core/cli/root-surface.ts +0 -74
  101. package/src/core/cli/runtime-preflight.ts +0 -438
  102. package/src/core/completion/index.ts +0 -88
  103. package/src/core/completion/shells/bash.ts +0 -459
  104. package/src/core/completion/shells/fish.ts +0 -259
  105. package/src/core/completion/shells/powershell.ts +0 -439
  106. package/src/core/completion/shells/shared.ts +0 -283
  107. package/src/core/completion/shells/zsh.ts +0 -381
  108. package/src/core/config/index.ts +0 -417
  109. package/src/core/config/package-json.ts +0 -560
  110. package/src/core/errors/index.ts +0 -193
  111. package/src/core/execution/index.ts +0 -268
  112. package/src/core/help/ansi.ts +0 -144
  113. package/src/core/help/index.ts +0 -516
  114. package/src/core/json-schema/index.ts +0 -891
  115. package/src/core/json-schema/meta-descriptions.generated.ts +0 -185
  116. package/src/core/output/activity.ts +0 -575
  117. package/src/core/output/bind.ts +0 -59
  118. package/src/core/output/contracts.ts +0 -194
  119. package/src/core/output/display-value.ts +0 -48
  120. package/src/core/output/index.ts +0 -704
  121. package/src/core/output/renderers.ts +0 -125
  122. package/src/core/output/writer.ts +0 -46
  123. package/src/core/parse/index.ts +0 -681
  124. package/src/core/prompt/index.ts +0 -583
  125. package/src/core/resolve/args.ts +0 -144
  126. package/src/core/resolve/coerce.ts +0 -432
  127. package/src/core/resolve/config.ts +0 -26
  128. package/src/core/resolve/contracts.ts +0 -135
  129. package/src/core/resolve/errors.ts +0 -227
  130. package/src/core/resolve/flags.ts +0 -255
  131. package/src/core/resolve/index.ts +0 -108
  132. package/src/core/resolve/property.ts +0 -99
  133. package/src/core/schema/activity.ts +0 -240
  134. package/src/core/schema/arg.ts +0 -719
  135. package/src/core/schema/command.ts +0 -1498
  136. package/src/core/schema/flag.ts +0 -801
  137. package/src/core/schema/index.ts +0 -91
  138. package/src/core/schema/middleware.ts +0 -171
  139. package/src/core/schema/prompt.ts +0 -156
  140. package/src/core/schema/run.ts +0 -198
  141. package/src/core/schema-dsl/index.ts +0 -109
  142. package/src/core/schema-dsl/parse.ts +0 -262
  143. package/src/core/schema-dsl/runtime.ts +0 -609
  144. package/src/core/schema-dsl/to-json-schema.ts +0 -102
  145. package/src/core/testkit/index.ts +0 -123
  146. package/src/index.ts +0 -179
  147. package/src/runtime/adapter.ts +0 -303
  148. package/src/runtime/auto.ts +0 -110
  149. package/src/runtime/bun.ts +0 -55
  150. package/src/runtime/deno.ts +0 -369
  151. package/src/runtime/detect.ts +0 -105
  152. package/src/runtime/index.ts +0 -21
  153. package/src/runtime/node-builtins.d.ts +0 -27
  154. package/src/runtime/node.ts +0 -300
  155. package/src/runtime/paths.ts +0 -64
  156. package/src/runtime/support.ts +0 -135
  157. package/src/runtime.ts +0 -31
  158. package/src/strings.ts +0 -34
  159. package/src/testkit.ts +0 -25
  160. package/src/version.ts +0 -20
@@ -1,252 +0,0 @@
1
- /**
2
- * Root-level help formatter for the CLI program.
3
- *
4
- * Separate from `help/formatHelp()` which renders per-command help —
5
- * different concerns, different format.
6
- *
7
- * @module dreamcli/core/cli/root-help
8
- * @internal
9
- */
10
-
11
- import { osc8, padEnd, wrapText } from '#internals/core/help/ansi.ts';
12
- import type { HelpOptions } from '#internals/core/help/index.ts';
13
- import { formatHelpSections } from '#internals/core/help/index.ts';
14
- import type { CommandSchema } from '#internals/core/schema/command.ts';
15
- import { resolveRootSurface } from './root-surface.ts';
16
-
17
- // Re-use CLISchema inline to avoid circular import through the barrel.
18
- // Only the shape matters — we read `.name`, `.version`, `.description`, `.commands`,
19
- // `.defaultCommand`, `.helpLinks`.
20
- /** Structural subset of `CLISchema` — avoids circular imports through the barrel. */
21
- interface CLISchemaLike {
22
- readonly name: string;
23
- readonly version: string | undefined;
24
- readonly description: string | undefined;
25
- readonly commands: ReadonlyArray<{
26
- readonly schema: CommandSchema;
27
- }>;
28
- readonly defaultCommand: { readonly schema: CommandSchema } | undefined;
29
- readonly helpLinks?:
30
- | {
31
- readonly name: string | undefined;
32
- readonly version: string | undefined;
33
- }
34
- | undefined;
35
- }
36
-
37
- // --- Root help formatter
38
-
39
- /**
40
- * Generate root-level help text for the CLI program.
41
- *
42
- * Shows program name, version, description, usage line, and available
43
- * commands. When the default command is the only visible top-level
44
- * command, merges the root summary with that command's detailed help.
45
- *
46
- * @internal
47
- */
48
- function formatRootHelp(schema: CLISchemaLike, options?: HelpOptions): string {
49
- const width = options?.width ?? 80;
50
- const hyperlinks = options?.hyperlinks === true;
51
- const rootSurface = resolveRootSurface(schema);
52
- if (rootSurface.hasSingleVisibleDefault) {
53
- const defaultCommand = rootSurface.visibleDefaultCommand;
54
- if (defaultCommand !== undefined) {
55
- const sections = buildRootSections(
56
- schema,
57
- rootSurface.visibleCommands,
58
- rootSurface.visibleDefaultCommand,
59
- width,
60
- hyperlinks,
61
- );
62
- const usageIndex = sections.findIndex((section) => section.startsWith('Usage: '));
63
- const commandSections = [
64
- ...formatHelpSections(defaultCommand, {
65
- ...options,
66
- binName: schema.name,
67
- isDefaultHelp: true,
68
- }),
69
- ];
70
- const commandUsage = commandSections.shift();
71
- if (usageIndex !== -1 && commandUsage !== undefined) {
72
- sections[usageIndex] = mergeUsageSections(sections[usageIndex] ?? '', commandUsage);
73
- }
74
- if (
75
- defaultCommand.description !== undefined &&
76
- schema.description !== undefined &&
77
- defaultCommand.description === schema.description
78
- ) {
79
- commandSections.shift();
80
- }
81
- sections.push(...commandSections);
82
- return `${sections.join('\n\n')}\n`;
83
- }
84
- }
85
-
86
- const sections = buildRootSections(
87
- schema,
88
- rootSurface.visibleCommands,
89
- rootSurface.visibleDefaultCommand,
90
- width,
91
- hyperlinks,
92
- );
93
- const placeholder = commandPlaceholder(
94
- rootSurface.visibleCommands,
95
- rootSurface.visibleDefaultCommand,
96
- );
97
- sections.push(
98
- placeholder.length > 0
99
- ? `Run '${schema.name} ${placeholder} --help' for more information.`
100
- : `Run '${schema.name} --help' for more information.`,
101
- );
102
-
103
- return `${sections.join('\n\n')}\n`;
104
- }
105
-
106
- /**
107
- * Assemble the header, description, usage, and commands sections for root help.
108
- *
109
- * @param schema - The CLI schema.
110
- * @param visibleCommands - Non-hidden top-level commands.
111
- * @param width - Terminal width for text wrapping.
112
- * @param hyperlinks - Whether to emit OSC 8 hyperlinks in the header.
113
- * @returns Ordered help sections (joined later with blank lines).
114
- * @internal
115
- */
116
- function buildRootSections(
117
- schema: CLISchemaLike,
118
- visibleCommands: readonly CommandSchema[],
119
- visibleDefaultCommand: CommandSchema | undefined,
120
- width: number,
121
- hyperlinks: boolean,
122
- ): string[] {
123
- const sections: string[] = [];
124
-
125
- // ---- Header: name + version ---------------------------------------------
126
- sections.push(formatHeader(schema, hyperlinks));
127
-
128
- // ---- Description --------------------------------------------------------
129
- if (schema.description !== undefined) {
130
- sections.push(schema.description);
131
- }
132
-
133
- // ---- Usage line ---------------------------------------------------------
134
- const placeholder = commandPlaceholder(visibleCommands, visibleDefaultCommand);
135
- sections.push(
136
- placeholder.length > 0
137
- ? `Usage: ${schema.name} ${placeholder} [options]`
138
- : `Usage: ${schema.name} [options]`,
139
- );
140
-
141
- // ---- Commands list (skip hidden) ----------------------------------------
142
- if (visibleCommands.length > 0) {
143
- sections.push(formatRootCommandsSection(visibleCommands, visibleDefaultCommand?.name, width));
144
- }
145
-
146
- return sections;
147
- }
148
-
149
- /**
150
- * Render the header line (`name vX.Y.Z`).
151
- *
152
- * When `hyperlinks` is enabled and the schema carries link URLs (via
153
- * `CLIBuilder.links()`, possibly derived from package.json metadata), the
154
- * name and version are wrapped in OSC 8 hyperlinks. The header is the only
155
- * place links are emitted — usage lines, hints, and the commands table stay
156
- * plain.
157
- *
158
- * @param schema - The CLI schema.
159
- * @param hyperlinks - Whether OSC 8 hyperlinks may be emitted.
160
- * @returns The header line.
161
- * @internal
162
- */
163
- function formatHeader(schema: CLISchemaLike, hyperlinks: boolean): string {
164
- const links = hyperlinks ? schema.helpLinks : undefined;
165
- const name = links?.name !== undefined ? osc8(links.name, schema.name) : schema.name;
166
- if (schema.version === undefined) return name;
167
- const version = `v${schema.version}`;
168
- return `${name} ${links?.version !== undefined ? osc8(links.version, version) : version}`;
169
- }
170
-
171
- /**
172
- * Return the usage-line placeholder for commands (`<command>`, `[command]`, or empty).
173
- *
174
- * @param visibleCommands - Non-hidden top-level commands.
175
- * @param defaultCommand - The default command, if any.
176
- * @returns Placeholder string for the usage line.
177
- * @internal
178
- */
179
- function commandPlaceholder(
180
- visibleCommands: readonly CommandSchema[],
181
- defaultCommand: CommandSchema | undefined,
182
- ): string {
183
- if (visibleCommands.length === 0 && defaultCommand === undefined) {
184
- return '';
185
- }
186
-
187
- return defaultCommand !== undefined ? '[command]' : '<command>';
188
- }
189
-
190
- /**
191
- * Format the "Commands:" section with aligned names and descriptions.
192
- *
193
- * @param visibleCommands - Non-hidden top-level commands.
194
- * @param defaultName - Name of the default command (appends " (default)" tag).
195
- * @param width - Terminal width for description wrapping.
196
- * @returns Formatted commands block.
197
- * @internal
198
- */
199
- function formatRootCommandsSection(
200
- visibleCommands: readonly CommandSchema[],
201
- defaultName: string | undefined,
202
- width: number,
203
- ): string {
204
- const lines: string[] = ['Commands:'];
205
- const GAP = 2;
206
- const DEFAULT_TAG = ' (default)';
207
-
208
- // Compute max command name length for alignment (account for default tag)
209
- let maxNameLen = 0;
210
- for (const cmd of visibleCommands) {
211
- const tagLen = cmd.name === defaultName ? DEFAULT_TAG.length : 0;
212
- const nameLen = cmd.name.length + tagLen;
213
- if (nameLen > maxNameLen) {
214
- maxNameLen = nameLen;
215
- }
216
- }
217
-
218
- const descCol = 2 + maxNameLen + GAP; // 2 for indent
219
- for (const cmd of visibleCommands) {
220
- const isDefault = cmd.name === defaultName;
221
- const label = isDefault ? `${cmd.name}${DEFAULT_TAG}` : cmd.name;
222
- const padded = padEnd(` ${label}`, descCol);
223
- const desc = cmd.description ?? '';
224
- if (desc.length === 0) {
225
- lines.push(padded.trimEnd());
226
- } else {
227
- lines.push(`${padded}${wrapText(desc, width, descCol)}`);
228
- }
229
- }
230
-
231
- return lines.join('\n');
232
- }
233
-
234
- /**
235
- * Merge root and default-command usage lines into a single block.
236
- *
237
- * @param rootUsage - The root usage line (e.g. `Usage: mycli [command] [options]`).
238
- * @param commandUsage - The default command's usage line.
239
- * @returns Combined usage block with aligned continuation.
240
- * @internal
241
- */
242
- function mergeUsageSections(rootUsage: string, commandUsage: string): string {
243
- const usagePrefix = 'Usage: ';
244
- const commandSuffix = commandUsage.startsWith(usagePrefix)
245
- ? commandUsage.slice(usagePrefix.length)
246
- : commandUsage;
247
- return `${rootUsage}\n${' '.repeat(usagePrefix.length)}${commandSuffix}`;
248
- }
249
-
250
- // --- Exports
251
-
252
- export { formatRootHelp };
@@ -1,74 +0,0 @@
1
- /**
2
- * Shared root-surface analysis for help and completion rendering.
3
- *
4
- * Answers structural questions about what the CLI root looks like:
5
- * which top-level commands are visible, whether the default command is
6
- * visible, and whether the root is effectively a single visible default.
7
- *
8
- * @module dreamcli/core/cli/root-surface
9
- * @internal
10
- */
11
-
12
- import type { CommandSchema } from '#internals/core/schema/command.ts';
13
-
14
- /**
15
- * Structural CLI shape needed for root-surface analysis.
16
- *
17
- * Uses structural typing to avoid importing the full `CLISchema` and
18
- * creating unnecessary cross-module coupling.
19
- *
20
- * @internal
21
- */
22
- interface RootSurfaceSchemaLike {
23
- readonly commands: ReadonlyArray<{
24
- readonly schema: CommandSchema;
25
- }>;
26
- readonly defaultCommand: { readonly schema: CommandSchema } | undefined;
27
- }
28
-
29
- /**
30
- * Normalized root shape shared by help and completion logic.
31
- *
32
- * @internal
33
- */
34
- interface RootSurface {
35
- readonly visibleCommands: readonly CommandSchema[];
36
- readonly visibleDefaultCommand: CommandSchema | undefined;
37
- readonly hasSingleVisibleDefault: boolean;
38
- readonly hasVisibleSiblingCommands: boolean;
39
- }
40
-
41
- /**
42
- * Resolve the visible shape of the CLI root.
43
- *
44
- * Hidden commands are excluded from the visible command list. Hidden
45
- * default commands remain executable, but are not surfaced through
46
- * help or completions.
47
- *
48
- * @internal
49
- */
50
- function resolveRootSurface(schema: RootSurfaceSchemaLike): RootSurface {
51
- const visibleCommands = schema.commands
52
- .map((command) => command.schema)
53
- .filter((command) => !command.hidden);
54
- const rawDefaultCommand = schema.defaultCommand?.schema;
55
- const visibleDefaultCommand =
56
- rawDefaultCommand !== undefined && !rawDefaultCommand.hidden ? rawDefaultCommand : undefined;
57
- const hasSingleVisibleDefault =
58
- visibleDefaultCommand !== undefined &&
59
- visibleCommands.length === 1 &&
60
- visibleCommands[0]?.name === visibleDefaultCommand.name;
61
- const hasVisibleSiblingCommands =
62
- visibleDefaultCommand !== undefined &&
63
- visibleCommands.some((command) => command.name !== visibleDefaultCommand.name);
64
-
65
- return {
66
- visibleCommands,
67
- visibleDefaultCommand,
68
- hasSingleVisibleDefault,
69
- hasVisibleSiblingCommands,
70
- };
71
- }
72
-
73
- export type { RootSurface, RootSurfaceSchemaLike };
74
- export { resolveRootSurface };