@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,57 +0,0 @@
1
- //#region src/core/cli/propagate.ts
2
- /**
3
- * Collect propagated flags from a command path.
4
- *
5
- * The command path is an ordered array of {@linkcode CommandSchema} from the root
6
- * ancestor to the target command that will actually execute. Each ancestor's
7
- * flags marked `propagate: true` are accumulated. If a descendant (including
8
- * the target) defines a flag with the same name — regardless of whether the
9
- * descendant's flag has `propagate: true` — it shadows the ancestor's flag.
10
- *
11
- * The target command's own flags are **not** included in the result. This
12
- * function returns only the *inherited* propagated flags that should be merged
13
- * into the target command's flag set before resolution.
14
- *
15
- * @param commandPath - Ordered schemas from root ancestor to target (inclusive).
16
- * Must contain at least one element (the target itself). When the path has
17
- * only one element, no ancestors exist and the result is empty.
18
- *
19
- * @returns A record of propagated flag schemas keyed by flag name. Empty when
20
- * the path has no ancestors or no ancestor flags have `propagate: true`.
21
- *
22
- * @example
23
- * ```ts
24
- * // Given: root (--verbose [propagate]) → db → migrate
25
- * // Where migrate does NOT define --verbose
26
- * const inherited = collectPropagatedFlags([rootSchema, dbSchema, migrateSchema]);
27
- * // inherited = { verbose: <FlagSchema from root> }
28
- *
29
- * // If db also defines --verbose (shadowing root):
30
- * const inherited2 = collectPropagatedFlags([rootSchema, dbSchemaWithVerbose, migrateSchema]);
31
- * // inherited2 = { verbose: <FlagSchema from db> }
32
- * ```
33
- */
34
- function collectPropagatedFlags(commandPath) {
35
- if (commandPath.length <= 1) return {};
36
- const accumulated = {};
37
- for (let i = 0; i < commandPath.length - 1; i++) {
38
- const ancestor = commandPath[i];
39
- if (ancestor === void 0) continue;
40
- for (const [name, flagSchema] of Object.entries(ancestor.flags)) if (flagSchema.propagate) {
41
- let shadowedByDescendant = false;
42
- for (let j = i + 1; j < commandPath.length - 1; j++) {
43
- const descendant = commandPath[j];
44
- if (descendant !== void 0 && Object.hasOwn(descendant.flags, name)) {
45
- shadowedByDescendant = true;
46
- break;
47
- }
48
- }
49
- if (!shadowedByDescendant) accumulated[name] = flagSchema;
50
- }
51
- }
52
- const target = commandPath[commandPath.length - 1];
53
- if (target !== void 0) for (const name of Object.keys(target.flags)) delete accumulated[name];
54
- return accumulated;
55
- }
56
- //#endregion
57
- export { collectPropagatedFlags };
@@ -1,19 +0,0 @@
1
- import { BuiltinsConfig } from "./builtins.mjs";
2
- import { CommandSchema } from "../schema/command.mjs";
3
- //#region src/core/cli/reserved-flags.d.ts
4
- /**
5
- * Reject command trees declaring a flag the CLI root already owns.
6
- *
7
- * @param version - The CLI's declared version; `undefined` leaves
8
- * `--version`/`-V` available to commands.
9
- * @param commands - Command trees to walk. `undefined` entries are skipped so
10
- * callers can pass an absent default command directly.
11
- * @param builtins - Built-in state; a released built-in reserves nothing.
12
- * `undefined` keeps every built-in on.
13
- * @throws {@linkcode CLIError} `RESERVED_FLAG` for the first collision found.
14
- *
15
- * @internal
16
- */
17
- declare function assertNoReservedFlagCollisions(version: string | undefined, commands: readonly (CommandSchema | undefined)[], builtins?: BuiltinsConfig): void;
18
- //#endregion
19
- export { assertNoReservedFlagCollisions };
@@ -1,158 +0,0 @@
1
- import { CLIError } from "../errors/index.mjs";
2
- import { getFlagAliasNames, getFlagNegatedName } from "../schema/flag.mjs";
3
- import { BUILTIN_NAMES, builtinEnabled, builtinSpelling, builtinTokens } from "./builtins.mjs";
4
- //#region src/core/cli/reserved-flags.ts
5
- /**
6
- * Build-time guard for command flags the CLI root already owns.
7
- *
8
- * `--json`, `--quiet`/`-q` and `--help`/`-h` never reach a command handler, and
9
- * `--version`/`-V` joins them once the CLI declares a version. A command flag
10
- * spelled the same way can never be set, so registering one throws
11
- * {@linkcode CLIError} `RESERVED_FLAG` here rather than building a CLI whose
12
- * flag silently stays at its default (#84).
13
- *
14
- * A built-in released through `.builtins({ <name>: 'off' })` drops out of the
15
- * reserved set, which is what makes the flag declarable (#86).
16
- *
17
- * @module dreamcli/core/cli/reserved-flags
18
- * @internal
19
- */
20
- /** Remedy for a reserved token whose only fix is a different spelling. */
21
- const RENAME = "Rename the flag";
22
- /** Why the root never hands a command the tokens it strips from argv. */
23
- const STRIPPED = "The root strips that token before dispatch";
24
- /** Why a command never receives `--help`, in either interception path. */
25
- const HELP_INTERCEPTED = "A help request renders before flags are parsed";
26
- /** Why a command never receives `--version`. */
27
- const VERSION_INTERCEPTED = "The root intercepts that token before dispatch";
28
- /** Extra clause offered for `--quiet`, which has a framework equivalent. */
29
- const STATUS_ALTERNATIVE = "use out.status() for output that root --quiet suppresses";
30
- /** Offer the `.builtins()` opt-out alongside renaming. */
31
- function releaseRemedy(name, ...alternatives) {
32
- return [
33
- RENAME,
34
- ...alternatives,
35
- `release the built-in with .builtins({ ${name}: 'off' }) before registering the command`
36
- ].join(", or ");
37
- }
38
- /** Why the root owns each built-in's tokens. */
39
- const BUILTIN_EFFECTS = {
40
- help: HELP_INTERCEPTED,
41
- json: STRIPPED,
42
- quiet: STRIPPED
43
- };
44
- /** How a collision with each built-in is fixed. */
45
- const BUILTIN_REMEDIES = {
46
- help: releaseRemedy("help"),
47
- json: releaseRemedy("json"),
48
- quiet: releaseRemedy("quiet", STATUS_ALTERNATIVE)
49
- };
50
- /** Reservation for `--version`/`-V`, active once the CLI declares a version. */
51
- const VERSION_RESERVED = {
52
- rootSpelling: "--version",
53
- effect: VERSION_INTERCEPTED,
54
- remedy: RENAME
55
- };
56
- /** Tokens the root owns only once a version is configured. */
57
- const VERSION_TOKENS = ["version", "V"];
58
- /**
59
- * The tokens a CLI's commands may not spell.
60
- *
61
- * Built from the shared built-in spelling table, so the reserved set and the spellings
62
- * the root actually reads cannot drift, and a released built-in is absent here
63
- * by construction.
64
- */
65
- function reservedTokens(version, builtins) {
66
- const reserved = /* @__PURE__ */ new Map();
67
- for (const name of BUILTIN_NAMES) {
68
- if (!builtinEnabled(builtins, name)) continue;
69
- const entry = {
70
- rootSpelling: builtinSpelling(name),
71
- effect: BUILTIN_EFFECTS[name],
72
- remedy: BUILTIN_REMEDIES[name]
73
- };
74
- for (const token of builtinTokens(name)) reserved.set(token, entry);
75
- }
76
- if (version !== void 0) for (const token of VERSION_TOKENS) reserved.set(token, VERSION_RESERVED);
77
- return reserved;
78
- }
79
- /** Render a bare token the way argv spells it. */
80
- function spellingOf(token) {
81
- return token.length === 1 ? `-${token}` : `--${token}`;
82
- }
83
- /** Every spelling one flag answers to, paired with the declaration it came from. */
84
- function flagSpellings(flagName, flagSchema) {
85
- const spellings = [[flagName, "name"]];
86
- for (const alias of getFlagAliasNames(flagSchema, { includeHidden: true })) spellings.push([alias, "alias"]);
87
- const negated = getFlagNegatedName(flagName, flagSchema);
88
- if (negated !== void 0) spellings.push([negated, "negation"]);
89
- return spellings;
90
- }
91
- /**
92
- * Find the first flag in a command tree whose spelling is reserved.
93
- *
94
- * @param schema - Command to walk, including its nested subcommands.
95
- * @param reserved - Reserved tokens for the current CLI configuration.
96
- * @returns The collision, or `undefined` when the tree is clean.
97
- *
98
- * @internal
99
- */
100
- function findReservedCollision(schema, reserved) {
101
- for (const [flagName, flagSchema] of Object.entries(schema.flags)) for (const [token, origin] of flagSpellings(flagName, flagSchema)) {
102
- const match = reserved.get(token);
103
- if (match === void 0) continue;
104
- return {
105
- commandName: schema.name,
106
- flagName,
107
- spelling: spellingOf(token),
108
- origin,
109
- reserved: match
110
- };
111
- }
112
- for (const child of schema.commands) {
113
- const nested = findReservedCollision(child, reserved);
114
- if (nested !== void 0) return nested;
115
- }
116
- }
117
- /** Describe the colliding declaration the way the error opens. */
118
- function subjectOf(collision) {
119
- switch (collision.origin) {
120
- case "name": return `defines a '${collision.spelling}' flag`;
121
- case "alias": return `defines a '${collision.spelling}' alias on flag '${collision.flagName}'`;
122
- case "negation": return `defines a '${collision.spelling}' negated spelling on flag '${collision.flagName}'`;
123
- }
124
- }
125
- /** Build the `RESERVED_FLAG` error for a collision. */
126
- function reservedFlagError(collision) {
127
- return new CLIError(`Command '${collision.commandName}' ${subjectOf(collision)}, which is reserved by the root '${collision.reserved.rootSpelling}' flag. ${collision.reserved.effect}, so the command can never receive it`, {
128
- code: "RESERVED_FLAG",
129
- details: {
130
- command: collision.commandName,
131
- flag: collision.flagName
132
- },
133
- suggest: collision.reserved.remedy
134
- });
135
- }
136
- /**
137
- * Reject command trees declaring a flag the CLI root already owns.
138
- *
139
- * @param version - The CLI's declared version; `undefined` leaves
140
- * `--version`/`-V` available to commands.
141
- * @param commands - Command trees to walk. `undefined` entries are skipped so
142
- * callers can pass an absent default command directly.
143
- * @param builtins - Built-in state; a released built-in reserves nothing.
144
- * `undefined` keeps every built-in on.
145
- * @throws {@linkcode CLIError} `RESERVED_FLAG` for the first collision found.
146
- *
147
- * @internal
148
- */
149
- function assertNoReservedFlagCollisions(version, commands, builtins) {
150
- const reserved = reservedTokens(version, builtins);
151
- for (const schema of commands) {
152
- if (schema === void 0) continue;
153
- const collision = findReservedCollision(schema, reserved);
154
- if (collision !== void 0) throw reservedFlagError(collision);
155
- }
156
- }
157
- //#endregion
158
- export { assertNoReservedFlagCollisions };
@@ -1,53 +0,0 @@
1
- import { BuiltinsConfig } from "./builtins.mjs";
2
- import { CommandSchema } from "../schema/command.mjs";
3
- import { HelpOptions } from "../help/index.mjs";
4
- //#region src/core/cli/root-help.d.ts
5
- /** Structural subset of `CLISchema` — avoids circular imports through the barrel. */
6
- interface CLISchemaLike {
7
- readonly name: string;
8
- readonly version: string | undefined;
9
- readonly description: string | undefined;
10
- readonly commands: readonly CommandSchema[];
11
- readonly defaultCommand: CommandSchema | undefined;
12
- /** Whether the default is also a named route — listed in `Commands:` when so. */
13
- readonly defaultCommandRouted?: boolean | undefined;
14
- readonly helpLinks?: {
15
- readonly name: string | undefined;
16
- readonly version: string | undefined;
17
- } | undefined;
18
- readonly completionsFlag?: {
19
- readonly shells: readonly string[];
20
- } | undefined;
21
- /**
22
- * Config discovery settings. Only its presence is read — defined means
23
- * `.config()` enabled the built-in `--config <path>` flag, so root help
24
- * advertises it in `Global options:`.
25
- */
26
- readonly configSettings?: {
27
- readonly appName: string;
28
- } | undefined;
29
- /**
30
- * Built-in flag state. A built-in set to `'off'` belongs to the commands, so
31
- * `Global options:` stops advertising it. Optional so hand-built schema-like
32
- * objects keep every built-in.
33
- */
34
- readonly builtins?: BuiltinsConfig | undefined;
35
- }
36
- /**
37
- * Generate root-level help text for the CLI program.
38
- *
39
- * Shows program name, version, description, usage line, and available
40
- * subcommands. The default command is the CLI's root *surface*: its arguments
41
- * and flags are rendered inline (unless `inlineDefault` is `false`) and it is
42
- * omitted from the `Commands:` list unless `showDefaultInCommands` is set. When
43
- * `.completions({ as: 'flag' })` is active, the eager `--completions <shell>`
44
- * flag is advertised in the `Flags:` section.
45
- *
46
- * A built-in released through `.builtins({ <name>: 'off' })` drops out of
47
- * `Global options:`, and releasing `help` also drops the `--help` footer hint.
48
- *
49
- * @internal
50
- */
51
- declare function formatRootHelp(schema: CLISchemaLike, options?: HelpOptions): string;
52
- //#endregion
53
- export { formatRootHelp };
@@ -1,221 +0,0 @@
1
- import { createFlagSchema } from "../schema/flag.mjs";
2
- import { command } from "../schema/command.mjs";
3
- import { BUILTIN_NAMES, BUILTIN_SPECS, builtinEnabled, builtinFlagForms } from "./builtins.mjs";
4
- import { resolveRootSurface } from "./root-surface.mjs";
5
- import { resolveHelpTheme } from "../help/theme.mjs";
6
- import { osc8, padEnd, wrapText } from "../help/ansi.mjs";
7
- import { formatFlagEntriesBlock, formatHelpSections } from "../help/index.mjs";
8
- //#region src/core/cli/root-help.ts
9
- /**
10
- * Root-level help formatter for the CLI program.
11
- *
12
- * Separate from `help/formatHelp()` which renders per-command help —
13
- * different concerns, different format.
14
- *
15
- * @module dreamcli/core/cli/root-help
16
- * @internal
17
- */
18
- /**
19
- * Generate root-level help text for the CLI program.
20
- *
21
- * Shows program name, version, description, usage line, and available
22
- * subcommands. The default command is the CLI's root *surface*: its arguments
23
- * and flags are rendered inline (unless `inlineDefault` is `false`) and it is
24
- * omitted from the `Commands:` list unless `showDefaultInCommands` is set. When
25
- * `.completions({ as: 'flag' })` is active, the eager `--completions <shell>`
26
- * flag is advertised in the `Flags:` section.
27
- *
28
- * A built-in released through `.builtins({ <name>: 'off' })` drops out of
29
- * `Global options:`, and releasing `help` also drops the `--help` footer hint.
30
- *
31
- * @internal
32
- */
33
- function formatRootHelp(schema, options) {
34
- const width = options?.width ?? 80;
35
- const binName = options?.binName ?? schema.name;
36
- const hyperlinks = options?.hyperlinks === true;
37
- const inlineDefault = options?.inlineDefault ?? true;
38
- const showDefaultInCommands = options?.showDefaultInCommands ?? false;
39
- const theme = resolveHelpTheme(options?.colors, options?.theme);
40
- const surface = resolveRootSurface(schema);
41
- const defaultCommand = surface.visibleDefaultCommand;
42
- const defaultIsSoleSurface = !surface.hasVisibleSubcommands && schema.completionsFlag === void 0;
43
- const inlineDefaultCommand = inlineDefault || defaultIsSoleSurface ? defaultCommand : void 0;
44
- const surfaceCommand = resolveSurfaceCommand(schema, inlineDefaultCommand);
45
- const inline = surfaceCommand !== void 0;
46
- const sections = [formatHeader(schema, hyperlinks, theme)];
47
- if (schema.description !== void 0) sections.push(schema.description);
48
- const placeholder = surface.hasVisibleSubcommands ? defaultCommand !== void 0 ? "[command]" : "<command>" : "";
49
- const usageTitle = theme.sectionTitle("Usage:");
50
- const rootUsage = placeholder.length > 0 ? `${usageTitle} ${theme.usageBin(binName)} ${theme.placeholder(placeholder)} ${theme.placeholder("[options]")}` : `${usageTitle} ${theme.usageBin(binName)} ${theme.placeholder("[options]")}`;
51
- let surfaceSections = [];
52
- if (inline && surfaceCommand !== void 0) surfaceSections = [...formatHelpSections(surfaceCommand, {
53
- ...options,
54
- binName,
55
- isDefaultHelp: true
56
- })];
57
- const surfaceUsage = surfaceSections.shift();
58
- if (inline && surfaceUsage !== void 0 && inlineDefaultCommand !== void 0) sections.push(surface.hasVisibleSubcommands ? mergeUsageSections(rootUsage, surfaceUsage, usageTitle) : surfaceUsage);
59
- else sections.push(rootUsage);
60
- const listDefaultInCommands = defaultCommand !== void 0 && (surface.defaultRouted || showDefaultInCommands);
61
- const listedCommands = listDefaultInCommands ? [...surface.visibleSubcommands, defaultCommand] : surface.visibleSubcommands;
62
- if (listedCommands.length > 0) sections.push(formatRootCommandsSection(listedCommands, listDefaultInCommands ? defaultCommand?.name : void 0, width, theme));
63
- if (inline && surfaceCommand !== void 0) {
64
- if (surfaceCommand.description !== void 0 && surfaceCommand.description === schema.description && surfaceSections[0] === surfaceCommand.description) surfaceSections.shift();
65
- sections.push(...surfaceSections);
66
- }
67
- const globalOptions = formatGlobalOptionsSection(schema, width, theme);
68
- if (globalOptions.length > 0) sections.push(globalOptions);
69
- if (builtinEnabled(schema.builtins, "help") && (options?.footer ?? surface.hasVisibleSubcommands)) {
70
- const footerPlaceholder = surface.hasVisibleSubcommands ? defaultCommand !== void 0 ? " [command]" : " <command>" : "";
71
- sections.push(`Run '${binName}${footerPlaceholder} --help' for more information.`);
72
- }
73
- return `${sections.join("\n\n")}\n`;
74
- }
75
- /**
76
- * Resolve the command rendered inline as the CLI's root surface.
77
- *
78
- * Returns the default command, augmented with the eager `--completions <shell>`
79
- * flag when `.completions({ as: 'flag' })` is active. When there is no default
80
- * command but the completions flag is configured, a synthetic surface carrying
81
- * just that flag is returned so the flag is still advertised. Returns
82
- * `undefined` when there is nothing to render inline.
83
- *
84
- * @internal
85
- */
86
- function resolveSurfaceCommand(schema, defaultCommand) {
87
- if (schema.completionsFlag === void 0) return defaultCommand;
88
- const base = defaultCommand ?? command(schema.name).schema;
89
- return {
90
- ...base,
91
- flags: {
92
- completions: completionsFlagSchema(schema.completionsFlag.shells),
93
- ...base.flags
94
- }
95
- };
96
- }
97
- /**
98
- * Build the synthetic, render-only flag schema for the eager `--completions`
99
- * flag. It never participates in parsing (the planner intercepts the flag
100
- * directly); it exists purely so root help can list
101
- * `--completions <bash|zsh|…>` in its `Flags:` section.
102
- *
103
- * @internal
104
- */
105
- function completionsFlagSchema(shells) {
106
- return createFlagSchema("enum", {
107
- description: "Print a shell completion script and exit",
108
- enumValues: shells
109
- });
110
- }
111
- /**
112
- * Render the header line (`name vX.Y.Z`).
113
- *
114
- * When `hyperlinks` is enabled and the schema carries link URLs (via
115
- * `CLIBuilder.links()`, possibly derived from package.json metadata), the
116
- * name and version are wrapped in OSC 8 hyperlinks. The header is the only
117
- * place links are emitted — usage lines, hints, and the commands table stay
118
- * plain.
119
- *
120
- * @param schema - The CLI schema.
121
- * @param hyperlinks - Whether OSC 8 hyperlinks may be emitted.
122
- * @param theme - Theme applied to the name and version (inside any hyperlink).
123
- * @returns The header line.
124
- * @internal
125
- */
126
- function formatHeader(schema, hyperlinks, theme) {
127
- const links = hyperlinks ? schema.helpLinks : void 0;
128
- const styledName = theme.headerName(schema.name);
129
- const name = links?.name !== void 0 ? osc8(links.name, styledName) : styledName;
130
- if (schema.version === void 0) return name;
131
- const version = theme.headerVersion(`v${schema.version}`);
132
- return `${name} ${links?.version !== void 0 ? osc8(links.version, version) : version}`;
133
- }
134
- /**
135
- * Format the "Commands:" section with aligned names and descriptions.
136
- *
137
- * @param visibleCommands - Non-hidden top-level commands.
138
- * @param defaultName - Name of the default command (appends " (default)" tag).
139
- * @param width - Terminal width for description wrapping.
140
- * @param theme - Theme applied to the title, command names, and default tag.
141
- * @returns Formatted commands block.
142
- * @internal
143
- */
144
- function formatRootCommandsSection(visibleCommands, defaultName, width, theme) {
145
- const lines = [theme.sectionTitle("Commands:")];
146
- const GAP = 2;
147
- const DEFAULT_TAG = " (default)";
148
- let maxNameLen = 0;
149
- for (const cmd of visibleCommands) {
150
- const tagLen = cmd.name === defaultName ? 10 : 0;
151
- const nameLen = cmd.name.length + tagLen;
152
- if (nameLen > maxNameLen) maxNameLen = nameLen;
153
- }
154
- const descCol = 2 + maxNameLen + GAP;
155
- for (const cmd of visibleCommands) {
156
- const label = cmd.name === defaultName ? `${theme.command(cmd.name)}${theme.annotation(DEFAULT_TAG)}` : theme.command(cmd.name);
157
- const padded = padEnd(` ${label}`, descCol);
158
- const desc = cmd.description ?? "";
159
- if (desc.length === 0) lines.push(padded.trimEnd());
160
- else lines.push(`${padded}${wrapText(desc, width, descCol)}`);
161
- }
162
- return lines.join("\n");
163
- }
164
- /**
165
- * Build the `Global options:` section advertising the active built-in flags.
166
- *
167
- * `-h, --help`, `--json`, and `-q, --quiet` are listed in {@link BUILTIN_NAMES}
168
- * order while the root owns them; `.builtins({ <name>: 'off' })` hands the token
169
- * to the commands and drops the entry. `-V, --version` is spliced in after the
170
- * `help` entry, so it keeps its place whether or not the root still owns
171
- * `--help`, and is shown only when the program declares a version.
172
- * `--config <path>` is listed only when `.config()` enabled config discovery.
173
- * The eager `--completions` flag is intentionally omitted, since it is
174
- * advertised via the inline surface when active.
175
- *
176
- * @param schema - The CLI schema (read for `version`, `configSettings`, and `builtins`).
177
- * @param width - Terminal width for description wrapping.
178
- * @param theme - Theme applied to the title and flag forms.
179
- * @returns Formatted `Global options:` block, or `''` when nothing is active.
180
- * @internal
181
- */
182
- function formatGlobalOptionsSection(schema, width, theme) {
183
- const entries = [];
184
- const pushBuiltin = (name) => {
185
- if (!builtinEnabled(schema.builtins, name)) return;
186
- entries.push({
187
- left: theme.flag(builtinFlagForms(name)),
188
- description: BUILTIN_SPECS[name].description
189
- });
190
- };
191
- for (const name of BUILTIN_NAMES) {
192
- pushBuiltin(name);
193
- if (name === "help" && schema.version !== void 0) entries.push({
194
- left: theme.flag("-V, --version"),
195
- description: "Print the version number and exit"
196
- });
197
- }
198
- if (schema.configSettings !== void 0) entries.push({
199
- left: `${theme.flag("--config")} ${theme.placeholder("<path>")}`,
200
- description: "Load configuration from the given file"
201
- });
202
- if (entries.length === 0) return "";
203
- return formatFlagEntriesBlock(theme.sectionTitle("Global options:"), entries, width);
204
- }
205
- /**
206
- * Merge root and default-command usage lines into a single block.
207
- *
208
- * @param rootUsage - The root usage line (e.g. `Usage: mycli [command] [options]`).
209
- * @param commandUsage - The default command's usage line.
210
- * @param usageTitle - The themed `Usage:` title — byte-identical in both lines
211
- * within one render, so the styled prefix strips cleanly.
212
- * @returns Combined usage block with aligned continuation.
213
- * @internal
214
- */
215
- function mergeUsageSections(rootUsage, commandUsage, usageTitle) {
216
- const usagePrefix = `${usageTitle} `;
217
- const commandSuffix = commandUsage.startsWith(usagePrefix) ? commandUsage.slice(usagePrefix.length) : commandUsage;
218
- return `${rootUsage}\n${" ".repeat(7)}${commandSuffix}`;
219
- }
220
- //#endregion
221
- export { formatRootHelp };
@@ -1,74 +0,0 @@
1
- import { BuiltinsConfig } from "./builtins.mjs";
2
- import { ParseError } from "../errors/index.mjs";
3
- import { Verbosity } from "../output/contracts.mjs";
4
- //#region src/core/cli/root-output-flags.d.ts
5
- /** Canonical name of a root output flag. @internal */
6
- type RootOutputFlagName = 'json' | 'quiet';
7
- /** What argv said about one root output flag. @internal */
8
- type RootFlagSelection = 'absent' | 'on' | 'off';
9
- /** Selections plus the argv the command layer should see. @internal */
10
- interface RootOutputFlagSelections {
11
- /** Selection for `--json`. */
12
- readonly json: RootFlagSelection;
13
- /** Selection for `--quiet`/`-q`. */
14
- readonly quiet: RootFlagSelection;
15
- /** Argv with the pre-separator root output flags removed. */
16
- readonly argv: readonly string[];
17
- }
18
- /** Every root output flag token carried a valid value. @internal */
19
- interface RootOutputFlagsOk extends RootOutputFlagSelections {
20
- /** Discriminant. */
21
- readonly kind: 'ok';
22
- }
23
- /** One token carried a value the boolean coercion rejected. @internal */
24
- interface RootOutputFlagsFailed extends RootOutputFlagSelections {
25
- /** Discriminant. */
26
- readonly kind: 'failed';
27
- /** Error from the first rejected token. */
28
- readonly error: ParseError;
29
- }
30
- /** Result of reading the root output flags out of argv. @internal */
31
- type RootOutputFlags = RootOutputFlagsOk | RootOutputFlagsFailed;
32
- /**
33
- * Read and strip the root output flags from argv.
34
- *
35
- * Only tokens before the `--` end-of-options separator are read or stripped, so
36
- * a literal after `--` reaches the command unchanged (#28). Repeated
37
- * occurrences follow the `'last'` duplicate policy `flag.boolean()` defaults to.
38
- *
39
- * A `'failed'` result still carries the selections and the stripped argv, so a
40
- * valid `--json` governs how the failure renders and a help or version request
41
- * can still be honoured ahead of it.
42
- *
43
- * @param argv - Raw argv tokens (excluding the binary/script path).
44
- * @param builtins - Built-in state; a released built-in's tokens are left in
45
- * argv untouched. `undefined` keeps both built-ins on.
46
- * @returns The selections, the stripped argv, and the first invalid value's
47
- * error when one occurred.
48
- * @internal
49
- */
50
- declare function readRootOutputFlags(argv: readonly string[], builtins?: BuiltinsConfig): RootOutputFlags;
51
- /**
52
- * Resolve JSON mode from the argv selection and an explicit override.
53
- *
54
- * An explicit `--json=false` wins over the override; the override applies when
55
- * argv says nothing.
56
- *
57
- * @param flags - Result of {@linkcode readRootOutputFlags}.
58
- * @param override - Caller-supplied `jsonMode`.
59
- * @returns Whether the run renders JSON.
60
- * @internal
61
- */
62
- declare function resolveRootJsonMode(flags: RootOutputFlags, override: boolean | undefined): boolean;
63
- /**
64
- * Resolve verbosity from the argv selection and an explicit override.
65
- *
66
- * @param flags - Result of {@linkcode readRootOutputFlags}.
67
- * @param override - Caller-supplied verbosity.
68
- * @returns `'quiet'` for `--quiet`, `'normal'` for `--quiet=false`, and the
69
- * override when argv says nothing.
70
- * @internal
71
- */
72
- declare function resolveRootVerbosity(flags: RootOutputFlags, override: Verbosity | undefined): Verbosity | undefined;
73
- //#endregion
74
- export { type RootOutputFlagName, type RootOutputFlags, readRootOutputFlags, resolveRootJsonMode, resolveRootVerbosity };