@kjanat/dreamcli 3.0.0 → 4.0.0-rc.1

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 (147) hide show
  1. package/CHANGELOG.md +967 -1
  2. package/README.md +9 -3
  3. package/dist/core/cli/builtins.d.mts +47 -0
  4. package/dist/core/cli/builtins.mjs +135 -0
  5. package/dist/core/cli/compiled.d.mts +29 -0
  6. package/dist/core/cli/compiled.mjs +76 -0
  7. package/dist/core/cli/dispatch.d.mts +9 -85
  8. package/dist/core/cli/help-links.d.mts +2 -14
  9. package/dist/core/cli/index.d.mts +282 -101
  10. package/dist/core/cli/index.mjs +497 -264
  11. package/dist/core/cli/planner.d.mts +13 -86
  12. package/dist/core/cli/planner.mjs +47 -30
  13. package/dist/core/cli/plugin.d.mts +1 -1
  14. package/dist/core/cli/propagate.mjs +1 -1
  15. package/dist/core/cli/reserved-flags.d.mts +1 -0
  16. package/dist/core/cli/reserved-flags.mjs +158 -0
  17. package/dist/core/cli/root-help.d.mts +1 -47
  18. package/dist/core/cli/root-help.mjs +37 -47
  19. package/dist/core/cli/root-output-flags.d.mts +1 -0
  20. package/dist/core/cli/root-output-flags.mjs +169 -0
  21. package/dist/core/cli/root-surface.d.mts +1 -68
  22. package/dist/core/cli/root-surface.mjs +2 -2
  23. package/dist/core/cli/runtime-preflight.d.mts +1 -199
  24. package/dist/core/cli/runtime-preflight.mjs +67 -17
  25. package/dist/core/completion/index.d.mts +2 -2
  26. package/dist/core/completion/shells/bash.d.mts +0 -1
  27. package/dist/core/completion/shells/bash.mjs +2 -1
  28. package/dist/core/completion/shells/fish.d.mts +0 -1
  29. package/dist/core/completion/shells/fish.mjs +2 -1
  30. package/dist/core/completion/shells/powershell.d.mts +0 -1
  31. package/dist/core/completion/shells/powershell.mjs +2 -1
  32. package/dist/core/completion/shells/shared.d.mts +3 -114
  33. package/dist/core/completion/shells/shared.mjs +9 -39
  34. package/dist/core/completion/shells/zsh.d.mts +0 -1
  35. package/dist/core/completion/shells/zsh.mjs +2 -1
  36. package/dist/core/config/index.d.mts +3 -3
  37. package/dist/core/config/index.mjs +2 -2
  38. package/dist/core/config/package-json.d.mts +2 -33
  39. package/dist/core/config/package-json.mjs +1 -34
  40. package/dist/core/errors/index.d.mts +7 -7
  41. package/dist/core/execution/index.d.mts +1 -48
  42. package/dist/core/execution/index.mjs +42 -27
  43. package/dist/core/help/ansi.d.mts +0 -11
  44. package/dist/core/help/index.d.mts +3 -35
  45. package/dist/core/help/index.mjs +29 -6
  46. package/dist/core/help/theme.d.mts +1 -21
  47. package/dist/core/json-schema/index.d.mts +279 -10
  48. package/dist/core/json-schema/index.mjs +482 -237
  49. package/dist/core/json-schema/meta-descriptions.generated.d.mts +79 -7
  50. package/dist/core/json-schema/meta-descriptions.generated.mjs +40 -6
  51. package/dist/core/output/activity.d.mts +1 -193
  52. package/dist/core/output/activity.mjs +1 -1
  53. package/dist/core/output/bind.d.mts +1 -37
  54. package/dist/core/output/contracts.d.mts +7 -13
  55. package/dist/core/output/contracts.mjs +1 -1
  56. package/dist/core/output/display-value.d.mts +1 -19
  57. package/dist/core/output/index.d.mts +5 -187
  58. package/dist/core/output/index.mjs +44 -9
  59. package/dist/core/output/renderers.d.mts +1 -45
  60. package/dist/core/output/writer.d.mts +0 -1
  61. package/dist/core/parse/index.d.mts +27 -5
  62. package/dist/core/parse/index.mjs +350 -227
  63. package/dist/core/parse/occurrences.d.mts +89 -0
  64. package/dist/core/parse/occurrences.mjs +114 -0
  65. package/dist/core/prompt/index.d.mts +3 -3
  66. package/dist/core/read-flags/index.d.mts +150 -0
  67. package/dist/core/read-flags/index.mjs +217 -0
  68. package/dist/core/resolve/args.d.mts +35 -4
  69. package/dist/core/resolve/args.mjs +132 -55
  70. package/dist/core/resolve/coerce.d.mts +66 -9
  71. package/dist/core/resolve/coerce.mjs +834 -270
  72. package/dist/core/resolve/config.d.mts +1 -10
  73. package/dist/core/resolve/contracts.d.mts +67 -44
  74. package/dist/core/resolve/errors.mjs +29 -21
  75. package/dist/core/resolve/flags.d.mts +36 -9
  76. package/dist/core/resolve/flags.mjs +129 -151
  77. package/dist/core/resolve/index.d.mts +8 -6
  78. package/dist/core/resolve/index.mjs +51 -18
  79. package/dist/core/resolve/path-checks.d.mts +47 -0
  80. package/dist/core/resolve/path-checks.mjs +102 -0
  81. package/dist/core/resolve/redaction.d.mts +12 -0
  82. package/dist/core/resolve/redaction.mjs +14 -0
  83. package/dist/core/resolve/stages.d.mts +85 -0
  84. package/dist/core/resolve/stages.mjs +170 -0
  85. package/dist/core/resolve/standard.d.mts +1 -24
  86. package/dist/core/resolve/standard.mjs +141 -43
  87. package/dist/core/schema/activity.d.mts +16 -16
  88. package/dist/core/schema/arg.d.mts +849 -71
  89. package/dist/core/schema/arg.mjs +727 -54
  90. package/dist/core/schema/brand.d.mts +17 -0
  91. package/dist/core/schema/cardinality.d.mts +301 -0
  92. package/dist/core/schema/cardinality.mjs +514 -0
  93. package/dist/core/schema/command.d.mts +181 -112
  94. package/dist/core/schema/command.mjs +305 -42
  95. package/dist/core/schema/flag.d.mts +515 -173
  96. package/dist/core/schema/flag.mjs +576 -78
  97. package/dist/core/schema/index.d.mts +11 -8
  98. package/dist/core/schema/index.mjs +10 -0
  99. package/dist/core/schema/middleware.d.mts +15 -12
  100. package/dist/core/schema/number-constraints.d.mts +5 -5
  101. package/dist/core/schema/prompt.d.mts +4 -4
  102. package/dist/core/schema/provenance.d.mts +99 -0
  103. package/dist/core/schema/provenance.mjs +28 -0
  104. package/dist/core/schema/run.d.mts +21 -60
  105. package/dist/core/schema/source.d.mts +179 -0
  106. package/dist/core/schema/source.mjs +206 -0
  107. package/dist/core/schema/standard.d.mts +12 -19
  108. package/dist/core/schema/stdin.d.mts +87 -0
  109. package/dist/core/schema/stdin.mjs +91 -0
  110. package/dist/core/schema/string-constraints.d.mts +16 -5
  111. package/dist/core/schema/string-constraints.mjs +18 -1
  112. package/dist/core/schema/value-parsers.d.mts +81 -9
  113. package/dist/core/schema/value-parsers.mjs +19 -1
  114. package/dist/core/schema/value.d.mts +242 -0
  115. package/dist/core/schema/value.mjs +573 -0
  116. package/dist/core/testkit/index.d.mts +28 -3
  117. package/dist/core/testkit/index.mjs +40 -26
  118. package/dist/index.d.mts +21 -16
  119. package/dist/index.mjs +10 -6
  120. package/dist/runtime/adapter.d.mts +3 -3
  121. package/dist/runtime/deno.d.mts +3 -3
  122. package/dist/runtime/detect.d.mts +2 -2
  123. package/dist/runtime/node.d.mts +3 -3
  124. package/dist/runtime/paths.d.mts +1 -31
  125. package/dist/runtime.d.mts +4 -4
  126. package/dist/strings.d.mts +1 -16
  127. package/dist/testkit.d.mts +2 -2
  128. package/dist/testkit.mjs +1 -1
  129. package/dist/version.d.mts +0 -13
  130. package/dist/version.mjs +2 -2
  131. package/dreamcli.schema.json +368 -78
  132. package/examples/interactive.ts +6 -5
  133. package/package.json +10 -9
  134. package/skills/cli-creation/SKILL.md +196 -0
  135. package/skills/cli-creation/agents/openai.yaml +4 -0
  136. package/skills/cli-creation/assets/templates/multi-command.bun-test.ts.tpl +20 -0
  137. package/skills/cli-creation/assets/templates/multi-command.test.ts.tpl +20 -0
  138. package/skills/cli-creation/assets/templates/multi-command.ts.tpl +89 -0
  139. package/skills/cli-creation/assets/templates/single-command.bun-test.ts.tpl +29 -0
  140. package/skills/cli-creation/assets/templates/single-command.test.ts.tpl +29 -0
  141. package/skills/cli-creation/assets/templates/single-command.ts.tpl +47 -0
  142. package/skills/cli-creation/references/consumer-workflow.md +65 -0
  143. package/skills/cli-creation/references/pattern-cookbook.md +451 -0
  144. package/skills/cli-creation/references/runtime-notes.md +29 -0
  145. package/skills/cli-creation/scripts/scaffold_cli.py +360 -0
  146. package/dist/core/resolve/property.d.mts +0 -51
  147. package/dist/core/resolve/property.mjs +0 -53
@@ -1,4 +1,6 @@
1
+ import { createFlagSchema } from "../schema/flag.mjs";
1
2
  import { command } from "../schema/command.mjs";
3
+ import { BUILTIN_NAMES, BUILTIN_SPECS, builtinEnabled, builtinFlagForms } from "./builtins.mjs";
2
4
  import { resolveRootSurface } from "./root-surface.mjs";
3
5
  import { osc8, padEnd, wrapText } from "../help/ansi.mjs";
4
6
  import { resolveHelpTheme } from "../help/theme.mjs";
@@ -23,6 +25,9 @@ import { formatFlagEntriesBlock, formatHelpSections } from "../help/index.mjs";
23
25
  * `.completions({ as: 'flag' })` is active, the eager `--completions <shell>`
24
26
  * flag is advertised in the `Flags:` section.
25
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
+ *
26
31
  * @internal
27
32
  */
28
33
  function formatRootHelp(schema, options) {
@@ -61,7 +66,7 @@ function formatRootHelp(schema, options) {
61
66
  }
62
67
  const globalOptions = formatGlobalOptionsSection(schema, width, theme);
63
68
  if (globalOptions.length > 0) sections.push(globalOptions);
64
- if (options?.footer ?? surface.hasVisibleSubcommands) {
69
+ if (builtinEnabled(schema.builtins, "help") && (options?.footer ?? surface.hasVisibleSubcommands)) {
65
70
  const footerPlaceholder = surface.hasVisibleSubcommands ? defaultCommand !== void 0 ? " [command]" : " <command>" : "";
66
71
  sections.push(`Run '${binName}${footerPlaceholder} --help' for more information.`);
67
72
  }
@@ -98,30 +103,10 @@ function resolveSurfaceCommand(schema, defaultCommand) {
98
103
  * @internal
99
104
  */
100
105
  function completionsFlagSchema(shells) {
101
- return {
102
- kind: "enum",
103
- presence: "optional",
104
- defaultValue: void 0,
105
- aliases: [],
106
- envVar: void 0,
107
- configPath: void 0,
106
+ return createFlagSchema("enum", {
108
107
  description: "Print a shell completion script and exit",
109
- enumValues: shells,
110
- elementSchema: void 0,
111
- separator: void 0,
112
- unique: false,
113
- numberConstraints: void 0,
114
- stringConstraints: void 0,
115
- pathChecks: void 0,
116
- valueHint: void 0,
117
- prompt: void 0,
118
- parseFn: void 0,
119
- standard: void 0,
120
- deprecated: void 0,
121
- propagate: false,
122
- negation: void 0,
123
- duplicates: "last"
124
- };
108
+ enumValues: shells
109
+ });
125
110
  }
126
111
  /**
127
112
  * Render the header line (`name vX.Y.Z`).
@@ -168,7 +153,8 @@ function formatRootCommandsSection(visibleCommands, defaultName, width, theme) {
168
153
  }
169
154
  const descCol = 2 + maxNameLen + GAP;
170
155
  for (const cmd of visibleCommands) {
171
- const padded = padEnd(` ${cmd.name === defaultName ? `${theme.command(cmd.name)}${theme.annotation(DEFAULT_TAG)}` : theme.command(cmd.name)}`, descCol);
156
+ const label = cmd.name === defaultName ? `${theme.command(cmd.name)}${theme.annotation(DEFAULT_TAG)}` : theme.command(cmd.name);
157
+ const padded = padEnd(` ${label}`, descCol);
172
158
  const desc = cmd.description ?? "";
173
159
  if (desc.length === 0) lines.push(padded.trimEnd());
174
160
  else lines.push(`${padded}${wrapText(desc, width, descCol)}`);
@@ -178,38 +164,42 @@ function formatRootCommandsSection(visibleCommands, defaultName, width, theme) {
178
164
  /**
179
165
  * Build the `Global options:` section advertising the active built-in flags.
180
166
  *
181
- * `--help, -h` and `--json` are always available; `--version, -V` is shown only
182
- * when the program declares a version; `--config <path>` only when `.config()`
183
- * enabled config discovery. The eager `--completions` flag is intentionally
184
- * omitted — it is advertised via the inline surface when active.
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.
185
175
  *
186
- * @param schema - The CLI schema (read for `version` and `configSettings`).
176
+ * @param schema - The CLI schema (read for `version`, `configSettings`, and `builtins`).
187
177
  * @param width - Terminal width for description wrapping.
188
178
  * @param theme - Theme applied to the title and flag forms.
189
- * @returns Formatted `Global options:` block (always non-empty).
179
+ * @returns Formatted `Global options:` block, or `''` when nothing is active.
190
180
  * @internal
191
181
  */
192
182
  function formatGlobalOptionsSection(schema, width, theme) {
193
- const entries = [{
194
- left: theme.flag("-h, --help"),
195
- description: "Show this help message and exit"
196
- }];
197
- if (schema.version !== void 0) entries.push({
198
- left: theme.flag("-V, --version"),
199
- description: "Print the version number and exit"
200
- });
201
- entries.push({
202
- left: theme.flag("--json"),
203
- description: "Emit machine-readable JSON output"
204
- });
205
- entries.push({
206
- left: theme.flag("-q, --quiet"),
207
- description: "Suppress informational output"
208
- });
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
+ }
209
198
  if (schema.configSettings !== void 0) entries.push({
210
199
  left: `${theme.flag("--config")} ${theme.placeholder("<path>")}`,
211
200
  description: "Load configuration from the given file"
212
201
  });
202
+ if (entries.length === 0) return "";
213
203
  return formatFlagEntriesBlock(theme.sectionTitle("Global options:"), entries, width);
214
204
  }
215
205
  /**
@@ -0,0 +1 @@
1
+ export {}
@@ -0,0 +1,169 @@
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,68 +1 @@
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: ReadonlyArray<{
13
- readonly schema: CommandSchema;
14
- }>;
15
- readonly defaultCommand: {
16
- readonly schema: CommandSchema;
17
- } | undefined;
18
- /**
19
- * Whether the default command is also exposed as a named route
20
- * (`.default(cmd, { route: true })`). Optional so hand-built schema-like
21
- * objects default to the surface-only behavior.
22
- */
23
- readonly defaultCommandRouted?: boolean | undefined;
24
- }
25
- /**
26
- * Normalized root shape shared by help and completion logic.
27
- *
28
- * Since v0.3 the default command is a distinct root *surface* rather than a
29
- * named subcommand: `.default()` no longer registers it under
30
- * {@link RootSurfaceSchemaLike.commands}. To stay robust against callers that
31
- * still place the default in the command list (e.g. hand-built test schemas),
32
- * {@link resolveRootSurface} always derives {@link RootSurface.visibleSubcommands}
33
- * by excluding the default command from the visible command list.
34
- *
35
- * @internal
36
- */
37
- interface RootSurface {
38
- /** All visible top-level commands as declared in `schema.commands`. */
39
- readonly visibleCommands: readonly CommandSchema[];
40
- /** Visible real subcommands — `visibleCommands` minus the default command. */
41
- readonly visibleSubcommands: readonly CommandSchema[];
42
- /** The visible default command, or `undefined` when none exists or it is hidden. */
43
- readonly visibleDefaultCommand: CommandSchema | undefined;
44
- /** Whether a visible default command exists. */
45
- readonly hasVisibleDefault: boolean;
46
- /** Whether any visible real subcommands exist (the default does not count). */
47
- readonly hasVisibleSubcommands: boolean;
48
- /**
49
- * Whether the visible default is also a named route (`.default(cmd, { route:
50
- * true })`), meaning it should be listed in `Commands:` beside its siblings
51
- * in addition to being rendered as the root surface.
52
- */
53
- readonly defaultRouted: boolean;
54
- }
55
- /**
56
- * Resolve the visible shape of the CLI root.
57
- *
58
- * Hidden commands are excluded from the visible command list. Hidden
59
- * default commands remain executable, but are not surfaced through
60
- * help or completions. The default command is reported separately from the
61
- * real subcommands so help and completion can render it as the root surface
62
- * instead of echoing it as a pseudo-subcommand.
63
- *
64
- * @internal
65
- */
66
- declare function resolveRootSurface(schema: RootSurfaceSchemaLike): RootSurface;
67
- //#endregion
68
- export { type RootSurface, type RootSurfaceSchemaLike, resolveRootSurface };
1
+ export {}
@@ -11,8 +11,8 @@
11
11
  * @internal
12
12
  */
13
13
  function resolveRootSurface(schema) {
14
- const visibleCommands = schema.commands.map((command) => command.schema).filter((command) => !command.hidden);
15
- const rawDefaultCommand = schema.defaultCommand?.schema;
14
+ const visibleCommands = schema.commands.filter((command) => !command.hidden);
15
+ const rawDefaultCommand = schema.defaultCommand;
16
16
  const visibleDefaultCommand = rawDefaultCommand !== void 0 && !rawDefaultCommand.hidden ? rawDefaultCommand : void 0;
17
17
  const visibleSubcommands = visibleDefaultCommand !== void 0 ? visibleCommands.filter((command) => command.name !== visibleDefaultCommand.name) : visibleCommands;
18
18
  return {
@@ -1,199 +1 @@
1
- import { Verbosity } from "../output/contracts.mjs";
2
- import "../output/index.mjs";
3
- import { PromptEngine } from "../prompt/index.mjs";
4
- import { CLIPlugin } from "./plugin.mjs";
5
- import { CLIError } from "../errors/index.mjs";
6
- import { HelpThemeFactory } from "../help/theme.mjs";
7
- import "../help/index.mjs";
8
- import { CommandSchema, ErasedCommand } from "../schema/command.mjs";
9
- import { ParseOptions } from "../parse/index.mjs";
10
- import { RuntimeAdapter } from "../../runtime/adapter.mjs";
11
- import { PackageJsonData } from "../config/package-json.mjs";
12
- import { HelpLinks } from "./help-links.mjs";
13
- import { CompletionOptions } from "../completion/shells/shared.mjs";
14
- import { Shell } from "../completion/index.mjs";
15
- import { FormatLoader } from "../config/index.mjs";
16
- //#region src/core/cli/runtime-preflight.d.ts
17
- /** Config discovery settings extracted from CLISchema for preflight use. @internal */
18
- interface RuntimeConfigSettings {
19
- /** Application name used to locate config files (e.g. `~/.config/<appName>/`). */
20
- readonly appName: string;
21
- /** Optional format loaders (JSON/YAML/TOML); `undefined` uses built-in JSON. */
22
- readonly loaders: readonly FormatLoader[] | undefined;
23
- }
24
- /**
25
- * Manifest discovery settings extracted from CLISchema for preflight use.
26
- *
27
- * Mirrors the public `ResolvedManifestSettings` shape (consumed structurally),
28
- * named with the `Runtime` prefix to match its {@link RuntimeConfigSettings}
29
- * sibling and avoid colliding with the exported public type.
30
- * @internal
31
- */
32
- interface RuntimeManifestSettings {
33
- /** Whether to infer the CLI binary name from `bin` keys or `name`. */
34
- readonly inferName: boolean;
35
- /** Strip a leading `@scope/` from the inferred `name` fallback. */
36
- readonly stripScope: boolean;
37
- /** Explicit anchor (resolved path) for discovery; `undefined` falls back to `adapter.cwd`. */
38
- readonly from: string | undefined;
39
- /** Candidate manifest filenames in priority order. */
40
- readonly files: readonly string[];
41
- /** Pre-loaded data; when set, discovery is skipped entirely. */
42
- readonly data: PackageJsonData | undefined;
43
- }
44
- /**
45
- * Structural subset of CLISchema used by runtime preflight.
46
- *
47
- * Decouples adapter-driven sourcing (config, package.json, stdin) from the
48
- * full CLIBuilder surface so preflight can be tested independently.
49
- * @internal
50
- */
51
- interface RuntimePreflightSchemaLike {
52
- /** CLI program name; may be overridden by package.json discovery or inheritance. */
53
- readonly name: string;
54
- /** Whether this CLI inherits its name from a parent (nested CLI embedding). */
55
- readonly inheritName: boolean;
56
- /** Declared version; `undefined` means version will be inferred from package.json if available. */
57
- readonly version: string | undefined;
58
- /** Declared description; `undefined` allows package.json inference. */
59
- readonly description: string | undefined;
60
- /** Registered top-level commands for dispatch planning during stdin detection. */
61
- readonly commands: readonly ErasedCommand[];
62
- /** Fallback command when no subcommand token matches. */
63
- readonly defaultCommand: ErasedCommand | undefined;
64
- /** Whether the default command is also exposed as a named top-level route. */
65
- readonly defaultCommandRouted: boolean;
66
- /** Config file discovery settings; `undefined` disables config loading. */
67
- readonly configSettings: RuntimeConfigSettings | undefined;
68
- /** Package.json discovery settings; `undefined` disables package.json inference. */
69
- readonly packageJsonSettings: RuntimeManifestSettings | undefined;
70
- /** Root-help header link targets; `undefined` fields may be derived from package.json. */
71
- readonly helpLinks: HelpLinks | undefined;
72
- /** Whether `.completions()` registered the built-in completions command/flag. */
73
- readonly hasBuiltInCompletions: boolean;
74
- /** Eager `--completions <shell>` flag config; `undefined` disables interception. */
75
- readonly completionsFlag: {
76
- readonly shells: readonly Shell[];
77
- readonly options: CompletionOptions | undefined;
78
- } | undefined;
79
- /** Consumer-configured root-help defaults. */
80
- readonly helpConfig: {
81
- readonly inlineDefault?: boolean;
82
- readonly showDefaultInCommands?: boolean;
83
- readonly footer?: boolean;
84
- readonly width?: number;
85
- readonly hyperlinks?: boolean;
86
- readonly theme?: HelpThemeFactory;
87
- } | undefined;
88
- /** Flag-parsing behavior settings (e.g. case parity). */
89
- readonly flagSettings: ParseOptions | undefined;
90
- /** Plugins forwarded into the execution pipeline. */
91
- readonly plugins: readonly CLIPlugin[];
92
- }
93
- /**
94
- * Caller-supplied overrides for runtime preflight.
95
- *
96
- * When provided, these bypass adapter auto-detection (useful for testing
97
- * and the `CLIRunOptions` public surface).
98
- * @internal
99
- */
100
- interface RuntimePreflightOptions {
101
- /** Environment variables override; bypasses adapter env when set. */
102
- readonly env?: Readonly<Record<string, string | undefined>>;
103
- /** Pre-loaded config object; skips config file discovery when set. */
104
- readonly config?: Readonly<Record<string, unknown>>;
105
- /** Pre-read stdin data; `null` means stdin was explicitly empty. */
106
- readonly stdinData?: string | null;
107
- /** Custom prompt engine; bypasses terminal prompter auto-creation. */
108
- readonly prompter?: PromptEngine;
109
- /** Output verbosity level override. */
110
- readonly verbosity?: Verbosity;
111
- /** Force JSON output mode regardless of `--json` flag presence. */
112
- readonly jsonMode?: boolean;
113
- /** TTY detection override; bypasses adapter TTY check. */
114
- readonly isTTY?: boolean;
115
- /** Filesystem probe override for `flag.path()` checks; bypasses the adapter probe. */
116
- readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
117
- /** Directory creation override for `flag.path()` `create` checks; bypasses the adapter. */
118
- readonly mkdir?: (path: string) => Promise<void>;
119
- }
120
- /**
121
- * Fully resolved runtime inputs ready for the execution pipeline.
122
- *
123
- * All adapter vs. caller-override decisions are settled by the time this
124
- * is constructed; the executor treats these as final truth.
125
- * @internal
126
- */
127
- interface RuntimeExecutionInputs {
128
- /** Resolved environment variables (from adapter or caller override). */
129
- readonly env: Readonly<Record<string, string | undefined>>;
130
- /** Whether stdout is a TTY (controls color, spinners, interactive prompts). */
131
- readonly isTTY: boolean;
132
- /** Whether structured JSON output mode is active. */
133
- readonly jsonMode: boolean;
134
- /** Output verbosity level. */
135
- readonly verbosity: Verbosity;
136
- /** Pre-read stdin data if the invocation declared stdin-mode args. */
137
- readonly stdinData?: string | null;
138
- /** Prompt engine for interactive flag resolution; absent in non-TTY. */
139
- readonly prompter?: PromptEngine;
140
- /** Loaded config data for the config resolution step. */
141
- readonly config?: Readonly<Record<string, unknown>>;
142
- /** Filesystem probe (from the adapter) for `flag.path()` checks. */
143
- readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
144
- /** Directory creation (from the adapter) for `flag.path()` `create` checks. */
145
- readonly mkdir?: (path: string) => Promise<void>;
146
- }
147
- /** Preflight succeeded — all runtime inputs are resolved and ready for execution. @internal */
148
- interface ReadyRuntimePreflight {
149
- /** Discriminant — preflight completed without errors. */
150
- readonly kind: 'ready';
151
- /** Schema after package.json discovery and name inheritance applied. */
152
- readonly schema: RuntimePreflightSchemaLike;
153
- /** Argv with valid runtime `--config` tokens stripped out. */
154
- readonly filteredArgv: readonly string[];
155
- /** Fully resolved runtime inputs for the execution pipeline. */
156
- readonly inputs: RuntimeExecutionInputs;
157
- }
158
- /** Preflight failed during config file discovery/loading. @internal */
159
- interface RuntimeConfigErrorPreflight {
160
- /** Discriminant — config loading produced a structured error. */
161
- readonly kind: 'config-error';
162
- /** The config discovery/parse error to render. */
163
- readonly error: CLIError;
164
- /** Whether JSON output was requested (needed to choose error rendering). */
165
- readonly jsonMode: boolean;
166
- }
167
- /** Discriminated union of preflight outcomes — either ready or config-error. @internal */
168
- type RuntimePreflightResult = ReadyRuntimePreflight | RuntimeConfigErrorPreflight;
169
- /** Options bag for {@linkcode prepareRuntimePreflight}. @internal */
170
- interface PrepareRuntimePreflightOptions {
171
- /** CLI schema subset driving preflight decisions. */
172
- readonly schema: RuntimePreflightSchemaLike;
173
- /** Runtime adapter providing argv, env, stdin, and filesystem access. */
174
- readonly adapter: RuntimeAdapter;
175
- /** Caller-supplied overrides; `undefined` means auto-detect everything. */
176
- readonly options: RuntimePreflightOptions | undefined;
177
- /** Name inherited from a parent CLI (nested embedding); `undefined` for standalone. */
178
- readonly inheritedName: string | undefined;
179
- }
180
- /** Extract and strip valid runtime `--config` forms from argv, returning path + filtered tokens. @internal */
181
- declare function extractConfigFlag(argv: readonly string[]): {
182
- readonly configPath: string | undefined;
183
- readonly filteredArgv: readonly string[];
184
- };
185
- /** Check whether a single command's args declare stdin-mode and argv leaves them unresolved. @internal */
186
- declare function commandInvocationNeedsStdin(schema: CommandSchema, argv: readonly string[], flagSettings?: ParseOptions): boolean;
187
- /** Plan the invocation and check whether the matched command needs stdin data. @internal */
188
- declare function invocationNeedsStdin(schema: RuntimePreflightSchemaLike, argv: readonly string[]): boolean;
189
- /**
190
- * Run all adapter-driven sourcing work before command execution.
191
- *
192
- * Discovers config files, reads package.json metadata, detects stdin needs,
193
- * wires up the prompt engine, and resolves output policy overrides into a
194
- * single {@linkcode RuntimePreflightResult}.
195
- * @internal
196
- */
197
- declare function prepareRuntimePreflight(options: PrepareRuntimePreflightOptions): Promise<RuntimePreflightResult>;
198
- //#endregion
199
- export { type PrepareRuntimePreflightOptions, type ReadyRuntimePreflight, type RuntimeExecutionInputs, type RuntimePreflightOptions, type RuntimePreflightResult, type RuntimePreflightSchemaLike, commandInvocationNeedsStdin, extractConfigFlag, invocationNeedsStdin, prepareRuntimePreflight };
1
+ export {}