@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,169 +0,0 @@
1
- import { ParseError } from "../errors/index.mjs";
2
- import { flag } from "../schema/flag.mjs";
3
- import { coerceFlagValue } from "../parse/index.mjs";
4
- import { BUILTIN_SPECS, builtinEnabled } from "./builtins.mjs";
5
- //#region src/core/cli/root-output-flags.ts
6
- /**
7
- * The root output-flag layer: `--json` and `--quiet`/`-q`.
8
- *
9
- * These flags belong to the CLI root instead of any command schema, so every
10
- * layer that needs the output mode (planner dispatch, `.execute()`, `.run()`
11
- * preflight, `resolveRenderContext()`, testkit `runCommand()`) reads and strips
12
- * them through {@linkcode readRootOutputFlags}. Values follow `flag.boolean()`:
13
- * bare presence, `=true`/`=1`, `=false`/`=0`, last occurrence wins, and an
14
- * invalid literal produces the parser's own `INVALID_VALUE` error.
15
- *
16
- * A built-in released through `.builtins({ json: 'off' })` is neither read nor
17
- * stripped here, so its tokens reach normal command parsing (#86).
18
- *
19
- * @module dreamcli/core/cli/root-output-flags
20
- * @internal
21
- */
22
- /** The schema root `--json`/`--quiet` share with a command-level boolean flag. */
23
- const rootBooleanSchema = flag.boolean().schema;
24
- /** The built-ins whose tokens this module reads, in stable order. */
25
- const ROOT_OUTPUT_NAMES = ["json", "quiet"];
26
- /** Index the spellings of one kind, taken from the shared built-in table. */
27
- function spellingIndex(kind) {
28
- const index = /* @__PURE__ */ new Map();
29
- for (const name of ROOT_OUTPUT_NAMES) for (const spelling of BUILTIN_SPECS[name][kind]) index.set(spelling, name);
30
- return index;
31
- }
32
- /** Long spellings, the only ones the tokenizer lets carry an inline `=value`. */
33
- const ROOT_LONG_SPELLINGS = spellingIndex("long");
34
- /** Short spellings, which have no inline-value form. */
35
- const ROOT_SHORT_SPELLINGS = spellingIndex("short");
36
- /** Coerce an inline `=value` the way a command-level boolean flag coerces it. */
37
- function coerceRootValue(name, spelling, raw) {
38
- try {
39
- return {
40
- kind: "flag",
41
- name,
42
- selection: coerceFlagValue(name, raw, rootBooleanSchema, spelling) === true ? "on" : "off"
43
- };
44
- } catch (error) {
45
- if (error instanceof ParseError) return {
46
- kind: "invalid",
47
- name,
48
- error
49
- };
50
- throw error;
51
- }
52
- }
53
- /** Look up a spelling, skipping built-ins the CLI released to its commands. */
54
- function ownedName(index, spelling, builtins) {
55
- const name = index.get(spelling);
56
- if (name === void 0 || !builtinEnabled(builtins, name)) return void 0;
57
- return name;
58
- }
59
- /** Resolve one pre-separator argv token against the root output flags. */
60
- function matchRootToken(token, builtins) {
61
- const shortName = ownedName(ROOT_SHORT_SPELLINGS, token, builtins);
62
- if (shortName !== void 0) return {
63
- kind: "flag",
64
- name: shortName,
65
- selection: "on"
66
- };
67
- const bareName = ownedName(ROOT_LONG_SPELLINGS, token, builtins);
68
- if (bareName !== void 0) return {
69
- kind: "flag",
70
- name: bareName,
71
- selection: "on"
72
- };
73
- const equals = token.indexOf("=");
74
- if (equals === -1) return { kind: "unrelated" };
75
- const spelling = token.slice(0, equals);
76
- const valuedName = ownedName(ROOT_LONG_SPELLINGS, spelling, builtins);
77
- if (valuedName === void 0) return { kind: "unrelated" };
78
- return coerceRootValue(valuedName, spelling, token.slice(equals + 1));
79
- }
80
- /**
81
- * Read and strip the root output flags from argv.
82
- *
83
- * Only tokens before the `--` end-of-options separator are read or stripped, so
84
- * a literal after `--` reaches the command unchanged (#28). Repeated
85
- * occurrences follow the `'last'` duplicate policy `flag.boolean()` defaults to.
86
- *
87
- * A `'failed'` result still carries the selections and the stripped argv, so a
88
- * valid `--json` governs how the failure renders and a help or version request
89
- * can still be honoured ahead of it.
90
- *
91
- * @param argv - Raw argv tokens (excluding the binary/script path).
92
- * @param builtins - Built-in state; a released built-in's tokens are left in
93
- * argv untouched. `undefined` keeps both built-ins on.
94
- * @returns The selections, the stripped argv, and the first invalid value's
95
- * error when one occurred.
96
- * @internal
97
- */
98
- function readRootOutputFlags(argv, builtins) {
99
- const separatorIndex = argv.indexOf("--");
100
- const head = separatorIndex === -1 ? argv : argv.slice(0, separatorIndex);
101
- const selections = {
102
- json: "absent",
103
- quiet: "absent"
104
- };
105
- const keptHead = [];
106
- const errors = /* @__PURE__ */ new Map();
107
- let stripped = false;
108
- for (const token of head) {
109
- const match = matchRootToken(token, builtins);
110
- if (match.kind === "unrelated") {
111
- keptHead.push(token);
112
- continue;
113
- }
114
- stripped = true;
115
- if (match.kind === "invalid") {
116
- errors.delete(match.name);
117
- errors.set(match.name, match.error);
118
- continue;
119
- }
120
- selections[match.name] = match.selection;
121
- errors.delete(match.name);
122
- }
123
- const strippedArgv = !stripped ? argv : separatorIndex === -1 ? keptHead : [...keptHead, ...argv.slice(separatorIndex)];
124
- const resolved = {
125
- json: selections.json,
126
- quiet: selections.quiet,
127
- argv: strippedArgv
128
- };
129
- const error = errors.values().next().value;
130
- return error !== void 0 ? {
131
- kind: "failed",
132
- ...resolved,
133
- error
134
- } : {
135
- kind: "ok",
136
- ...resolved
137
- };
138
- }
139
- /**
140
- * Resolve JSON mode from the argv selection and an explicit override.
141
- *
142
- * An explicit `--json=false` wins over the override; the override applies when
143
- * argv says nothing.
144
- *
145
- * @param flags - Result of {@linkcode readRootOutputFlags}.
146
- * @param override - Caller-supplied `jsonMode`.
147
- * @returns Whether the run renders JSON.
148
- * @internal
149
- */
150
- function resolveRootJsonMode(flags, override) {
151
- if (flags.json === "absent") return override === true;
152
- return flags.json === "on";
153
- }
154
- /**
155
- * Resolve verbosity from the argv selection and an explicit override.
156
- *
157
- * @param flags - Result of {@linkcode readRootOutputFlags}.
158
- * @param override - Caller-supplied verbosity.
159
- * @returns `'quiet'` for `--quiet`, `'normal'` for `--quiet=false`, and the
160
- * override when argv says nothing.
161
- * @internal
162
- */
163
- function resolveRootVerbosity(flags, override) {
164
- if (flags.quiet === "on") return "quiet";
165
- if (flags.quiet === "off") return "normal";
166
- return override;
167
- }
168
- //#endregion
169
- export { readRootOutputFlags, resolveRootJsonMode, resolveRootVerbosity };
@@ -1,64 +0,0 @@
1
- import { CommandSchema } from "../schema/command.mjs";
2
- //#region src/core/cli/root-surface.d.ts
3
- /**
4
- * Structural CLI shape needed for root-surface analysis.
5
- *
6
- * Uses structural typing to avoid importing the full `CLISchema` and
7
- * creating unnecessary cross-module coupling.
8
- *
9
- * @internal
10
- */
11
- interface RootSurfaceSchemaLike {
12
- readonly commands: readonly CommandSchema[];
13
- readonly defaultCommand: CommandSchema | undefined;
14
- /**
15
- * Whether the default command is also exposed as a named route
16
- * (`.default(cmd, { route: true })`). Optional so hand-built schema-like
17
- * objects default to the surface-only behavior.
18
- */
19
- readonly defaultCommandRouted?: boolean | undefined;
20
- }
21
- /**
22
- * Normalized root shape shared by help and completion logic.
23
- *
24
- * Since v0.3 the default command is a distinct root *surface* rather than a
25
- * named subcommand: `.default()` no longer registers it under
26
- * {@link RootSurfaceSchemaLike.commands}. To stay robust against callers that
27
- * still place the default in the command list (e.g. hand-built test schemas),
28
- * {@link resolveRootSurface} always derives {@link RootSurface.visibleSubcommands}
29
- * by excluding the default command from the visible command list.
30
- *
31
- * @internal
32
- */
33
- interface RootSurface {
34
- /** All visible top-level commands as declared in `schema.commands`. */
35
- readonly visibleCommands: readonly CommandSchema[];
36
- /** Visible real subcommands — `visibleCommands` minus the default command. */
37
- readonly visibleSubcommands: readonly CommandSchema[];
38
- /** The visible default command, or `undefined` when none exists or it is hidden. */
39
- readonly visibleDefaultCommand: CommandSchema | undefined;
40
- /** Whether a visible default command exists. */
41
- readonly hasVisibleDefault: boolean;
42
- /** Whether any visible real subcommands exist (the default does not count). */
43
- readonly hasVisibleSubcommands: boolean;
44
- /**
45
- * Whether the visible default is also a named route (`.default(cmd, { route:
46
- * true })`), meaning it should be listed in `Commands:` beside its siblings
47
- * in addition to being rendered as the root surface.
48
- */
49
- readonly defaultRouted: boolean;
50
- }
51
- /**
52
- * Resolve the visible shape of the CLI root.
53
- *
54
- * Hidden commands are excluded from the visible command list. Hidden
55
- * default commands remain executable, but are not surfaced through
56
- * help or completions. The default command is reported separately from the
57
- * real subcommands so help and completion can render it as the root surface
58
- * instead of echoing it as a pseudo-subcommand.
59
- *
60
- * @internal
61
- */
62
- declare function resolveRootSurface(schema: RootSurfaceSchemaLike): RootSurface;
63
- //#endregion
64
- export { type RootSurface, type RootSurfaceSchemaLike, resolveRootSurface };
@@ -1,28 +0,0 @@
1
- //#region src/core/cli/root-surface.ts
2
- /**
3
- * Resolve the visible shape of the CLI root.
4
- *
5
- * Hidden commands are excluded from the visible command list. Hidden
6
- * default commands remain executable, but are not surfaced through
7
- * help or completions. The default command is reported separately from the
8
- * real subcommands so help and completion can render it as the root surface
9
- * instead of echoing it as a pseudo-subcommand.
10
- *
11
- * @internal
12
- */
13
- function resolveRootSurface(schema) {
14
- const visibleCommands = schema.commands.filter((command) => !command.hidden);
15
- const rawDefaultCommand = schema.defaultCommand;
16
- const visibleDefaultCommand = rawDefaultCommand !== void 0 && !rawDefaultCommand.hidden ? rawDefaultCommand : void 0;
17
- const visibleSubcommands = visibleDefaultCommand !== void 0 ? visibleCommands.filter((command) => command.name !== visibleDefaultCommand.name) : visibleCommands;
18
- return {
19
- visibleCommands,
20
- visibleSubcommands,
21
- visibleDefaultCommand,
22
- hasVisibleDefault: visibleDefaultCommand !== void 0,
23
- hasVisibleSubcommands: visibleSubcommands.length > 0,
24
- defaultRouted: visibleDefaultCommand !== void 0 && schema.defaultCommandRouted === true
25
- };
26
- }
27
- //#endregion
28
- export { resolveRootSurface };
@@ -1,213 +0,0 @@
1
- import { BuiltinsConfig, BuiltinsDraft } from "./builtins.mjs";
2
- import { HelpThemeFactory } from "../help/theme.mjs";
3
- import { CLIError } from "../errors/index.mjs";
4
- import { Verbosity } from "../output/contracts.mjs";
5
- import { CommandSchema } from "../schema/command.mjs";
6
- import "../help/index.mjs";
7
- import "../output/index.mjs";
8
- import { PromptEngine } from "../prompt/index.mjs";
9
- import { ParseOptions } from "../parse/index.mjs";
10
- import { CompiledCLI } from "./compiled.mjs";
11
- import { RuntimeAdapter } from "../../runtime/adapter.mjs";
12
- import { PackageJsonData } from "../config/package-json.mjs";
13
- import { HelpLinks } from "./help-links.mjs";
14
- import { CompletionOptions } from "../completion/shells/shared.mjs";
15
- import { Shell } from "../completion/index.mjs";
16
- import { FormatLoader } from "../config/index.mjs";
17
- //#region src/core/cli/runtime-preflight.d.ts
18
- /** Config discovery settings extracted from CLISchema for preflight use. @internal */
19
- interface RuntimeConfigSettings {
20
- /** Application name used to locate config files (e.g. `~/.config/<appName>/`). */
21
- readonly appName: string;
22
- /** Optional format loaders (JSON/YAML/TOML); `undefined` uses built-in JSON. */
23
- readonly loaders: readonly FormatLoader[] | undefined;
24
- }
25
- /**
26
- * Manifest discovery settings extracted from CLISchema for preflight use.
27
- *
28
- * Mirrors the public `ResolvedManifestSettings` shape (consumed structurally),
29
- * named with the `Runtime` prefix to match its {@link RuntimeConfigSettings}
30
- * sibling and avoid colliding with the exported public type.
31
- * @internal
32
- */
33
- interface RuntimeManifestSettings {
34
- /** Whether to infer the CLI binary name from `bin` keys or `name`. */
35
- readonly inferName: boolean;
36
- /** Strip a leading `@scope/` from the inferred `name` fallback. */
37
- readonly stripScope: boolean;
38
- /** Explicit anchor (resolved path) for discovery; `undefined` falls back to `adapter.cwd`. */
39
- readonly from: string | undefined;
40
- /** Candidate manifest filenames in priority order. */
41
- readonly files: readonly string[];
42
- /** Pre-loaded data; when set, discovery is skipped entirely. */
43
- readonly data: PackageJsonData | undefined;
44
- }
45
- /**
46
- * Descriptive subset of CLISchema used by runtime preflight.
47
- *
48
- * Decouples adapter-driven sourcing (config, package.json, stdin) from the
49
- * full CLIBuilder surface so preflight can be tested independently. Preflight
50
- * rewrites fields of this shape and hands the result back; the executable half
51
- * of the program travels beside it as a {@linkcode CompiledCLI}.
52
- * @internal
53
- */
54
- interface RuntimePreflightSchemaLike {
55
- /** CLI program name; may be overridden by package.json discovery or inheritance. */
56
- readonly name: string;
57
- /** Whether this CLI inherits its name from a parent (nested CLI embedding). */
58
- readonly inheritName: boolean;
59
- /** Declared version; `undefined` means version will be inferred from package.json if available. */
60
- readonly version: string | undefined;
61
- /** Declared description; `undefined` allows package.json inference. */
62
- readonly description: string | undefined;
63
- /** Whether the default command is also exposed as a named top-level route. */
64
- readonly defaultCommandRouted: boolean;
65
- /** Config file discovery settings; `undefined` disables config loading. */
66
- readonly configSettings: RuntimeConfigSettings | undefined;
67
- /** Package.json discovery settings; `undefined` disables package.json inference. */
68
- readonly packageJsonSettings: RuntimeManifestSettings | undefined;
69
- /** Root-help header link targets; `undefined` fields may be derived from package.json. */
70
- readonly helpLinks: HelpLinks | undefined;
71
- /** Whether `.completions()` registered the built-in completions command/flag. */
72
- readonly hasBuiltInCompletions: boolean;
73
- /** Eager `--completions <shell>` flag config; `undefined` disables interception. */
74
- readonly completionsFlag: {
75
- readonly shells: readonly Shell[];
76
- readonly options: CompletionOptions | undefined;
77
- } | undefined;
78
- /** Consumer-configured root-help defaults. */
79
- readonly helpConfig: {
80
- readonly inlineDefault?: boolean;
81
- readonly showDefaultInCommands?: boolean;
82
- readonly footer?: boolean;
83
- readonly width?: number;
84
- readonly hyperlinks?: boolean;
85
- readonly theme?: HelpThemeFactory;
86
- } | undefined;
87
- /** Flag-parsing behavior settings (e.g. case parity). */
88
- readonly flagSettings: ParseOptions | undefined;
89
- /** Which built-in flags the root still owns; a released one is left in argv. */
90
- readonly builtins: BuiltinsDraft;
91
- }
92
- /**
93
- * Caller-supplied overrides for runtime preflight.
94
- *
95
- * When provided, these bypass adapter auto-detection (useful for testing
96
- * and the `CLIRunOptions` public surface).
97
- * @internal
98
- */
99
- interface RuntimePreflightOptions {
100
- /** Environment variables override; bypasses adapter env when set. */
101
- readonly env?: Readonly<Record<string, string | undefined>>;
102
- /** Pre-loaded config object; skips config file discovery when set. */
103
- readonly config?: Readonly<Record<string, unknown>>;
104
- /** Pre-read stdin data; `null` means stdin was explicitly empty. */
105
- readonly stdinData?: string | null;
106
- /** Custom prompt engine; bypasses terminal prompter auto-creation. */
107
- readonly prompter?: PromptEngine;
108
- /** Output verbosity level override. */
109
- readonly verbosity?: Verbosity;
110
- /** Force JSON output mode regardless of `--json` flag presence. */
111
- readonly jsonMode?: boolean;
112
- /** TTY detection override; bypasses adapter TTY check. */
113
- readonly isTTY?: boolean;
114
- /** Filesystem probe override for `flag.path()` checks; bypasses the adapter probe. */
115
- readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
116
- /** Directory creation override for `flag.path()` `create` checks; bypasses the adapter. */
117
- readonly mkdir?: (path: string) => Promise<void>;
118
- }
119
- /**
120
- * Fully resolved runtime inputs ready for the execution pipeline.
121
- *
122
- * All adapter vs. caller-override decisions are settled by the time this
123
- * is constructed; the executor treats these as final truth.
124
- * @internal
125
- */
126
- interface RuntimeExecutionInputs {
127
- /** Resolved environment variables (from adapter or caller override). */
128
- readonly env: Readonly<Record<string, string | undefined>>;
129
- /** Whether stdout is a TTY (controls color, spinners, interactive prompts). */
130
- readonly isTTY: boolean;
131
- /** Whether structured JSON output mode is active. */
132
- readonly jsonMode: boolean;
133
- /** Output verbosity level. */
134
- readonly verbosity: Verbosity;
135
- /** Pre-read stdin data if the invocation would select a stdin source. */
136
- readonly stdinData?: string | null;
137
- /** Prompt engine for interactive flag resolution; absent in non-TTY. */
138
- readonly prompter?: PromptEngine;
139
- /** Loaded config data for the config resolution step. */
140
- readonly config?: Readonly<Record<string, unknown>>;
141
- /** Filesystem probe (from the adapter) for `flag.path()` checks. */
142
- readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
143
- /** Directory creation (from the adapter) for `flag.path()` `create` checks. */
144
- readonly mkdir?: (path: string) => Promise<void>;
145
- }
146
- /** Preflight succeeded — all runtime inputs are resolved and ready for execution. @internal */
147
- interface ReadyRuntimePreflight {
148
- /** Discriminant — preflight completed without errors. */
149
- readonly kind: 'ready';
150
- /** Schema after package.json discovery and name inheritance applied. */
151
- readonly schema: RuntimePreflightSchemaLike;
152
- /** Argv with valid runtime `--config` tokens stripped out. */
153
- readonly filteredArgv: readonly string[];
154
- /** Fully resolved runtime inputs for the execution pipeline. */
155
- readonly inputs: RuntimeExecutionInputs;
156
- }
157
- /** Preflight failed before the CLI could start. @internal */
158
- interface RuntimeStartupErrorPreflight {
159
- /** Discriminant — a startup step produced a structured error. */
160
- readonly kind: 'startup-error';
161
- /** The startup error to render. */
162
- readonly error: CLIError;
163
- /** Whether JSON output was requested (needed to choose error rendering). */
164
- readonly jsonMode: boolean;
165
- }
166
- /** Discriminated union of preflight outcomes — either ready or startup-error. @internal */
167
- type RuntimePreflightResult = ReadyRuntimePreflight | RuntimeStartupErrorPreflight;
168
- /** Options bag for {@linkcode prepareRuntimePreflight}. @internal */
169
- interface PrepareRuntimePreflightOptions {
170
- /** CLI schema subset driving preflight decisions. */
171
- readonly schema: RuntimePreflightSchemaLike;
172
- /** Compiled execution graph, forwarded to the planner for stdin detection. */
173
- readonly compiled: CompiledCLI;
174
- /** Runtime adapter providing argv, env, stdin, and filesystem access. */
175
- readonly adapter: RuntimeAdapter;
176
- /** Caller-supplied overrides; `undefined` means auto-detect everything. */
177
- readonly options: RuntimePreflightOptions | undefined;
178
- /** Name inherited from a parent CLI (nested embedding); `undefined` for standalone. */
179
- readonly inheritedName: string | undefined;
180
- }
181
- /** Extract and strip valid runtime `--config` forms from argv, returning path + filtered tokens. @internal */
182
- declare function extractConfigFlag(argv: readonly string[]): {
183
- readonly configPath: string | undefined;
184
- readonly filteredArgv: readonly string[];
185
- };
186
- /**
187
- * Check whether this invocation will actually select a stdin source.
188
- *
189
- * A `'dash'` binding is eligible when its token is `-`. A `'missing'` binding is
190
- * eligible when argv left the input absent; env, config, prompt, and default do
191
- * not suppress the read, because the stdin fallback outranks all four.
192
- *
193
- * @param schema - The matched command's merged schema.
194
- * @param argv - The command's own argv slice.
195
- * @param flagSettings - Parser behavior settings.
196
- * @param builtins - Which built-in flags the root still owns.
197
- * @returns `true` when at least one input would read stdin.
198
- * @internal
199
- */
200
- declare function commandInvocationNeedsStdin(schema: CommandSchema, argv: readonly string[], flagSettings?: ParseOptions, builtins?: BuiltinsConfig): boolean;
201
- /** Plan the invocation and check whether the matched command needs stdin data. @internal */
202
- declare function invocationNeedsStdin(schema: RuntimePreflightSchemaLike, compiled: CompiledCLI, argv: readonly string[]): boolean;
203
- /**
204
- * Run all adapter-driven sourcing work before command execution.
205
- *
206
- * Discovers config files, reads package.json metadata, detects stdin needs,
207
- * wires up the prompt engine, and resolves output policy overrides into a
208
- * single {@linkcode RuntimePreflightResult}.
209
- * @internal
210
- */
211
- declare function prepareRuntimePreflight(options: PrepareRuntimePreflightOptions): Promise<RuntimePreflightResult>;
212
- //#endregion
213
- export { type PrepareRuntimePreflightOptions, type ReadyRuntimePreflight, type RuntimeExecutionInputs, type RuntimePreflightOptions, type RuntimePreflightResult, type RuntimePreflightSchemaLike, commandInvocationNeedsStdin, extractConfigFlag, invocationNeedsStdin, prepareRuntimePreflight };