@kjanat/dreamcli 3.0.1 → 4.0.0-rc.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (137) hide show
  1. package/CHANGELOG.md +962 -1
  2. package/README.md +7 -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 +173 -119
  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 +30 -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 +12 -11
  134. package/skills/cli-creation/SKILL.md +72 -16
  135. package/skills/cli-creation/references/pattern-cookbook.md +169 -11
  136. package/dist/core/resolve/property.d.mts +0 -51
  137. package/dist/core/resolve/property.mjs +0 -53
@@ -9,9 +9,9 @@
9
9
  * @module dreamcli/core/errors
10
10
  */
11
11
  /** Codes emitted during argv parsing. */
12
- type ParseErrorCode = 'UNKNOWN_FLAG' | 'UNKNOWN_COMMAND' | 'MISSING_VALUE' | 'INVALID_VALUE' | 'INVALID_SCHEMA' | 'DUPLICATE_FLAG' | 'UNEXPECTED_POSITIONAL';
12
+ type ParseErrorCode = "UNKNOWN_FLAG" | "UNKNOWN_COMMAND" | "MISSING_VALUE" | "INVALID_VALUE" | "INVALID_SCHEMA" | "DUPLICATE_FLAG" | "UNEXPECTED_POSITIONAL";
13
13
  /** Codes emitted during post-parse validation / resolution. */
14
- type ValidationErrorCode = 'REQUIRED_FLAG' | 'REQUIRED_ARG' | 'INVALID_ENUM' | 'TYPE_MISMATCH' | 'CONSTRAINT_VIOLATED';
14
+ type ValidationErrorCode = "REQUIRED_FLAG" | "REQUIRED_ARG" | "MISSING_STDIN" | "INVALID_ENUM" | "TYPE_MISMATCH" | "CONSTRAINT_VIOLATED";
15
15
  /** Any framework error code (extensible via `string & {}`). */
16
16
  type ErrorCode = ParseErrorCode | ValidationErrorCode | (string & {});
17
17
  /** Options accepted by the `CLIError` constructor. */
@@ -38,7 +38,7 @@ interface CLIErrorOptions {
38
38
  */
39
39
  declare class CLIError extends Error {
40
40
  /** Error class name, always `'CLIError'` for the base class. @override */
41
- readonly name: string;
41
+ override readonly name: string;
42
42
  /** Stable machine-readable identifier. */
43
43
  readonly code: ErrorCode;
44
44
  /** Process exit code (defaults to `1`). */
@@ -71,7 +71,7 @@ interface CLIErrorJSON {
71
71
  readonly details?: Readonly<Record<string, unknown>>;
72
72
  }
73
73
  /** Options for {@linkcode ParseError}. Code is narrowed to parse-specific codes. */
74
- interface ParseErrorOptions extends Omit<CLIErrorOptions, 'code' | 'exitCode'> {
74
+ interface ParseErrorOptions extends Omit<CLIErrorOptions, "code" | "exitCode"> {
75
75
  /** Parse-category error code (e.g. `'UNKNOWN_FLAG'`, `'MISSING_VALUE'`). */
76
76
  readonly code: ParseErrorCode;
77
77
  /**
@@ -87,14 +87,14 @@ interface ParseErrorOptions extends Omit<CLIErrorOptions, 'code' | 'exitCode'> {
87
87
  */
88
88
  declare class ParseError extends CLIError {
89
89
  /** Always `'ParseError'`. @override */
90
- readonly name: "ParseError";
90
+ override readonly name: "ParseError";
91
91
  /** Narrowed to parse-category codes. */
92
92
  readonly code: ParseErrorCode;
93
93
  /** Create a parse error with exit code defaulting to `2`. */
94
94
  constructor(message: string, options: ParseErrorOptions);
95
95
  }
96
96
  /** Options for {@linkcode ValidationError}. Code is narrowed to validation-specific codes. */
97
- interface ValidationErrorOptions extends Omit<CLIErrorOptions, 'code' | 'exitCode'> {
97
+ interface ValidationErrorOptions extends Omit<CLIErrorOptions, "code" | "exitCode"> {
98
98
  /** Validation-category error code (e.g. `'REQUIRED_FLAG'`, `'INVALID_ENUM'`). */
99
99
  readonly code: ValidationErrorCode;
100
100
  /**
@@ -110,7 +110,7 @@ interface ValidationErrorOptions extends Omit<CLIErrorOptions, 'code' | 'exitCod
110
110
  */
111
111
  declare class ValidationError extends CLIError {
112
112
  /** Always `'ValidationError'`. @override */
113
- readonly name: "ValidationError";
113
+ override readonly name: "ValidationError";
114
114
  /** Narrowed to validation-category codes. */
115
115
  readonly code: ValidationErrorCode;
116
116
  /** Create a validation error with exit code defaulting to `2`. */
@@ -1,48 +1 @@
1
- import { CapturedOutput } from "../output/index.mjs";
2
- import { CLIError } from "../errors/index.mjs";
3
- import { RunOptions, RunResult } from "../schema/run.mjs";
4
- import { CommandMeta, CommandSchema, Out, RunnableCommand } from "../schema/command.mjs";
5
- //#region src/core/execution/index.d.ts
6
- /**
7
- * Explicit executor input for a single command invocation.
8
- * @internal
9
- */
10
- interface CommandExecutionRequest {
11
- /** The command instance whose handler will be invoked. */
12
- readonly command: RunnableCommand;
13
- /** Raw argument tokens to parse (excluding the program name). */
14
- readonly argv: readonly string[];
15
- /** Output channel for handler and error rendering. */
16
- readonly out: Out;
17
- /** Frozen schema definition (flags, args, metadata) for parsing and resolution. */
18
- readonly schema: CommandSchema;
19
- /** Runtime metadata (binary name, version) propagated to the handler. */
20
- readonly meta: CommandMeta;
21
- /** Optional overrides for env, config, prompter, plugins, and JSON mode. */
22
- readonly options?: RunOptions;
23
- }
24
- /**
25
- * Minimal executor result before output buffers are assembled into `RunResult`.
26
- * @internal
27
- */
28
- interface CommandExecutionResult {
29
- /** Process exit code (`0` on success, error-specific otherwise). */
30
- readonly exitCode: number;
31
- /** The structured error if the command failed, `undefined` on success. */
32
- readonly error: CLIError | undefined;
33
- }
34
- /**
35
- * Run the full parse -> resolve -> plugin -> handler pipeline for one command.
36
- *
37
- * Handles `--help` short-circuit, plugin lifecycle hooks, deprecation warnings,
38
- * and error wrapping. Both CLI dispatch and testkit `runCommand` converge here.
39
- * @internal
40
- */
41
- declare function executeCommand(request: CommandExecutionRequest): Promise<CommandExecutionResult>;
42
- /**
43
- * Assemble a {@linkcode CommandExecutionResult} and captured output buffers into a public `RunResult`.
44
- * @internal
45
- */
46
- declare function buildRunResult(result: CommandExecutionResult, captured: CapturedOutput): RunResult;
47
- //#endregion
48
- export { type CommandExecutionRequest, type CommandExecutionResult, buildRunResult, executeCommand };
1
+ export {}
@@ -1,5 +1,6 @@
1
1
  import { CLIError } from "../errors/index.mjs";
2
- import { includesBeforeSeparator, parse } from "../parse/index.mjs";
2
+ import { parse, requestsHelp } from "../parse/index.mjs";
3
+ import { builtinEnabled } from "../cli/builtins.mjs";
3
4
  import { formatHelp } from "../help/index.mjs";
4
5
  import { generateCommandSchema } from "../json-schema/index.mjs";
5
6
  import { clearRequestedExitCode, getRequestedExitCode } from "../output/index.mjs";
@@ -7,6 +8,15 @@ import { createTestPrompter } from "../prompt/index.mjs";
7
8
  import { resolve } from "../resolve/index.mjs";
8
9
  //#region src/core/execution/index.ts
9
10
  /**
11
+ * Shared command execution seam.
12
+ *
13
+ * Centralizes the parse -> resolve -> plugin -> handler pipeline so CLI and
14
+ * testkit can converge on one owned execution path during the re-foundation.
15
+ *
16
+ * @module dreamcli/core/execution
17
+ * @internal
18
+ */
19
+ /**
10
20
  * Run the full parse -> resolve -> plugin -> handler pipeline for one command.
11
21
  *
12
22
  * Handles `--help` short-circuit, plugin lifecycle hooks, deprecation warnings,
@@ -17,7 +27,7 @@ async function executeCommand(request) {
17
27
  const { argv, command, meta, options, out, schema } = request;
18
28
  clearRequestedExitCode(out);
19
29
  try {
20
- if (includesBeforeSeparator(argv, "--help") || includesBeforeSeparator(argv, "-h")) {
30
+ if (builtinEnabled(options?.builtins, "help") && requestsHelp(argv)) {
21
31
  if (out.jsonMode || options?.jsonMode === true) {
22
32
  out.json(generateCommandSchema(schema, void 0, {
23
33
  name: options?.help?.binName ?? schema.name,
@@ -40,9 +50,9 @@ async function executeCommand(request) {
40
50
  }
41
51
  const handler = command.handler;
42
52
  if (handler === void 0) {
43
- const error = new CLIError(`Command '${command.schema.name}' has no action handler`, {
53
+ const error = new CLIError(`Command '${schema.name}' has no action handler`, {
44
54
  code: "NO_ACTION",
45
- suggest: `Add an .action() handler to the '${command.schema.name}' command`
55
+ suggest: `Add an .action() handler to the '${schema.name}' command`
46
56
  });
47
57
  out.error(error.message);
48
58
  return {
@@ -58,14 +68,15 @@ async function executeCommand(request) {
58
68
  });
59
69
  const parsed = parse(schema, argv, options?.flags);
60
70
  const effectivePrompter = options?.prompter ?? (options?.answers !== void 0 ? createTestPrompter(options.answers) : void 0);
61
- const resolved = await resolve(schema, parsed, {
71
+ const resolveOptions = {
62
72
  ...options?.stdinData !== void 0 ? { stdinData: options.stdinData } : {},
63
73
  ...options?.env !== void 0 ? { env: options.env } : {},
64
74
  ...options?.config !== void 0 ? { config: options.config } : {},
65
75
  ...effectivePrompter !== void 0 ? { prompter: effectivePrompter } : {},
66
76
  ...options?.stat !== void 0 ? { stat: options.stat } : {},
67
77
  ...options?.mkdir !== void 0 ? { mkdir: options.mkdir } : {}
68
- });
78
+ };
79
+ const resolved = await resolve(schema, parsed, resolveOptions);
69
80
  const resolvedParams = {
70
81
  args: resolved.args,
71
82
  flags: resolved.flags,
@@ -77,7 +88,7 @@ async function executeCommand(request) {
77
88
  await runResolvedHooks(options?.plugins, "afterResolve", resolvedParams);
78
89
  for (const deprecation of resolved.deprecations) out.warn(formatDeprecation(deprecation));
79
90
  await runResolvedHooks(options?.plugins, "beforeAction", resolvedParams);
80
- await executeWithExecutionSteps(command, handler, resolved.flags, resolved.args, out, meta);
91
+ await executeWithExecutionSteps(command, handler, resolved, out, meta);
81
92
  await runResolvedHooks(options?.plugins, "afterAction", resolvedParams);
82
93
  return {
83
94
  exitCode: getRequestedExitCode(out) ?? 0,
@@ -95,7 +106,8 @@ async function executeCommand(request) {
95
106
  error
96
107
  };
97
108
  }
98
- const wrapped = new CLIError(`Unexpected error: ${error instanceof Error ? error.message : String(error)}`, {
109
+ const message = error instanceof Error ? error.message : String(error);
110
+ const wrapped = new CLIError(`Unexpected error: ${message}`, {
99
111
  code: "UNEXPECTED_ERROR",
100
112
  cause: error
101
113
  });
@@ -124,12 +136,15 @@ async function runResolvedHooks(plugins, hookName, params) {
124
136
  if (hook !== void 0) await hook(params);
125
137
  }
126
138
  }
127
- async function executeWithExecutionSteps(command, handler, flags, args, out, meta) {
128
- const steps = command._executionSteps;
139
+ async function executeWithExecutionSteps(command, handler, resolved, out, meta) {
140
+ const steps = command.steps;
141
+ const { args, flags } = resolved;
142
+ const sources = resolved.provenance;
129
143
  let chain = async (ctx) => {
130
144
  await handler({
131
145
  flags,
132
146
  args,
147
+ sources,
133
148
  ctx,
134
149
  out,
135
150
  meta
@@ -145,6 +160,7 @@ async function executeWithExecutionSteps(command, handler, flags, args, out, met
145
160
  const additions = await step.handler({
146
161
  args,
147
162
  flags,
163
+ sources,
148
164
  ctx,
149
165
  out,
150
166
  meta
@@ -163,23 +179,22 @@ async function executeWithExecutionSteps(command, handler, flags, args, out, met
163
179
  });
164
180
  };
165
181
  break;
166
- case "middleware":
167
- chain = async (ctx) => {
168
- await step.handler({
169
- args,
170
- flags,
171
- ctx,
172
- out,
173
- meta,
174
- next: async (additions) => {
175
- await downstream({
176
- ...ctx,
177
- ...additions
178
- });
179
- }
180
- });
181
- };
182
- break;
182
+ case "middleware": chain = async (ctx) => {
183
+ await step.handler({
184
+ args,
185
+ flags,
186
+ sources,
187
+ ctx,
188
+ out,
189
+ meta,
190
+ next: async (additions) => {
191
+ await downstream({
192
+ ...ctx,
193
+ ...additions
194
+ });
195
+ }
196
+ });
197
+ };
183
198
  }
184
199
  }
185
200
  await chain({});
@@ -1,15 +1,4 @@
1
1
  //#region src/core/help/ansi.d.ts
2
- /**
3
- * ANSI/OSC-aware text helpers for help formatting.
4
- *
5
- * Terminal escape sequences (SGR colors, OSC 8 hyperlinks) occupy zero
6
- * columns when rendered, so width math must measure the *visible* text.
7
- * {@linkcode visibleWidth} strips escapes before counting, and the shared
8
- * {@linkcode padEnd}/{@linkcode wrapText} helpers build on it so aligned
9
- * tables and wrapped lines stay intact when escapes are present.
10
- *
11
- * @module dreamcli/core/help/ansi
12
- */
13
2
  /**
14
3
  * Remove ANSI CSI and OSC escape sequences from `text`.
15
4
  *
@@ -1,6 +1,6 @@
1
+ import { CommandSchema } from "../schema/command.mjs";
1
2
  import { HelpTheme, HelpThemeFactory } from "./theme.mjs";
2
3
  import { osc8, visibleWidth } from "./ansi.mjs";
3
- import { CommandSchema } from "../schema/command.mjs";
4
4
  import "../schema/index.mjs";
5
5
  import { Colors } from "ansispeck";
6
6
  //#region src/core/help/index.d.ts
@@ -22,7 +22,7 @@ interface HelpOptions {
22
22
  *
23
23
  * @defaultValue `'alphabetical'`
24
24
  */
25
- readonly flagOrder?: 'alphabetical' | 'declaration';
25
+ readonly flagOrder?: "alphabetical" | "declaration";
26
26
  /**
27
27
  * Custom comparator over flag long names for the `Flags:` table. When set,
28
28
  * it wins over {@link HelpOptions.flagOrder}.
@@ -62,8 +62,6 @@ interface HelpOptions {
62
62
  * explicitly to force it on or off.
63
63
  */
64
64
  readonly footer?: boolean;
65
- /** @internal Whether this usage line is being rendered as merged root/default help. */
66
- readonly isDefaultHelp?: boolean;
67
65
  /**
68
66
  * Gated ANSI palette used to style help output. Identity formatters mean
69
67
  * plain text. `CLIBuilder.execute()`/`.run()` thread the output channel's
@@ -82,22 +80,6 @@ interface HelpOptions {
82
80
  */
83
81
  readonly theme?: HelpThemeFactory;
84
82
  }
85
- /** Formatted flag entry for the flags table. @internal */
86
- interface FlagEntry {
87
- /** Preformatted flag names and value hint for the left table column. */
88
- readonly left: string;
89
- /** Preformatted help text for the description table column. */
90
- readonly description: string;
91
- }
92
- /**
93
- * Build the ordered help sections without joining them.
94
- *
95
- * @internal
96
- * @param schema - The {@link CommandSchema} to render.
97
- * @param options - Optional {@link HelpOptions} for width/bin name.
98
- * @returns Array of section strings (usage, description, commands, args, flags, examples).
99
- */
100
- declare function formatHelpSections(schema: CommandSchema, options?: HelpOptions): readonly string[];
101
83
  /**
102
84
  * Generate help text from a command schema.
103
85
  *
@@ -124,19 +106,5 @@ declare function formatHelpSections(schema: CommandSchema, options?: HelpOptions
124
106
  * ```
125
107
  */
126
108
  declare function formatHelp(schema: CommandSchema, options?: HelpOptions): string;
127
- /**
128
- * Render a titled two-column flag block from pre-built {@link FlagEntry} rows.
129
- *
130
- * Shared by the per-command `Flags:` section and the root-help `Global options:`
131
- * block (built-in flags), so column alignment and description wrapping stay
132
- * identical across both. Returns `''` when there are no entries.
133
- *
134
- * @param title - Section heading (e.g. `'Flags:'`, `'Global options:'`), pre-styled by the caller.
135
- * @param entries - Formatted left/description rows.
136
- * @param width - Terminal width for description wrapping.
137
- * @returns Multi-line block string, or `''` when `entries` is empty.
138
- * @internal
139
- */
140
- declare function formatFlagEntriesBlock(title: string, entries: readonly FlagEntry[], width: number): string;
141
109
  //#endregion
142
- export { type FlagEntry, type HelpOptions, type HelpTheme, type HelpThemeFactory, formatFlagEntriesBlock, formatHelp, formatHelpSections, osc8, visibleWidth };
110
+ export { type HelpOptions, type HelpTheme, type HelpThemeFactory, formatHelp, osc8, visibleWidth };
@@ -82,7 +82,25 @@ function formatValueHint(schema) {
82
82
  }
83
83
  }
84
84
  /**
85
- * Build description with env/config/prompt/default/required/deprecated annotations.
85
+ * Name what selects the stdin stream for an input, in the `[env: X]` style.
86
+ *
87
+ * `[stdin]` covers the default trigger, where both an explicit `-` and an
88
+ * absent input read the stream. The narrower triggers say which one applies, so
89
+ * a reader knows whether typing `-` is required.
90
+ *
91
+ * @param stdin - The input's stdin axis.
92
+ * @returns The annotation to render beside the description.
93
+ */
94
+ function formatStdinAnnotation(stdin) {
95
+ switch (stdin.when) {
96
+ case "dash": return "[stdin: '-']";
97
+ case "missing": return "[stdin: when omitted]";
98
+ case "dash-or-missing": return "[stdin]";
99
+ }
100
+ }
101
+ /**
102
+ * Build description with stdin/env/config/prompt/default/required/deprecated
103
+ * annotations.
86
104
  *
87
105
  * @param schema - The {@link FlagSchema} to describe.
88
106
  * @param theme - Theme applied to the metadata annotations (description stays plain).
@@ -92,11 +110,12 @@ function formatFlagDescription(schema, theme) {
92
110
  const parts = [];
93
111
  if (schema.description !== void 0) parts.push(schema.description);
94
112
  if (schema.deprecated !== void 0) parts.push(theme.deprecated(formatDeprecated(schema.deprecated)));
113
+ if (schema.stdin !== void 0) parts.push(theme.annotation(formatStdinAnnotation(schema.stdin)));
95
114
  if (schema.envVar !== void 0) parts.push(theme.annotation(`[env: ${schema.envVar}]`));
96
115
  if (schema.configPath !== void 0) parts.push(theme.annotation(`[config: ${schema.configPath}]`));
97
116
  if (schema.prompt !== void 0) parts.push(theme.annotation("[prompt]"));
98
- if (schema.presence === "required") parts.push(theme.annotation("[required]"));
99
- else if (schema.presence === "defaulted" && schema.kind !== "boolean" && schema.kind !== "count") parts.push(theme.defaultValue(`(default: ${formatHelpDefaultValue(schema.defaultValue)})`));
117
+ if (schema.presence === "required" && schema.defaultValue === void 0) parts.push(theme.annotation("[required]"));
118
+ else if ((schema.presence === "defaulted" || schema.defaultValue !== void 0) && schema.kind !== "boolean" && schema.kind !== "count") parts.push(theme.defaultValue(`(default: ${formatHelpDefaultValue(schema.defaultValue)})`));
100
119
  return parts.join(" ");
101
120
  }
102
121
  /**
@@ -153,11 +172,12 @@ function formatArgUsage(entry) {
153
172
  const { name, schema } = entry;
154
173
  const label = schema.kind === "enum" && schema.enumValues !== void 0 ? schema.enumValues.join("|") : name;
155
174
  const variadicSuffix = schema.variadic ? "..." : "";
156
- if (schema.presence === "required") return `<${label}>${variadicSuffix}`;
175
+ if (schema.presence === "required" && schema.defaultValue === void 0) return `<${label}>${variadicSuffix}`;
157
176
  return `[${label}]${variadicSuffix}`;
158
177
  }
159
178
  /**
160
- * Format arg description with annotations.
179
+ * Format arg description with stdin/env/config/prompt/default/deprecated
180
+ * annotations.
161
181
  *
162
182
  * @param schema - The {@link ArgSchema} to describe.
163
183
  * @param theme - Theme applied to the metadata annotations (description stays plain).
@@ -167,8 +187,11 @@ function formatArgDescription(schema, theme) {
167
187
  const parts = [];
168
188
  if (schema.description !== void 0) parts.push(schema.description);
169
189
  if (schema.deprecated !== void 0) parts.push(theme.deprecated(formatDeprecated(schema.deprecated)));
190
+ if (schema.stdin !== void 0) parts.push(theme.annotation(formatStdinAnnotation(schema.stdin)));
170
191
  if (schema.envVar !== void 0) parts.push(theme.annotation(`[env: ${schema.envVar}]`));
171
- if (schema.presence === "defaulted") parts.push(theme.defaultValue(`(default: ${formatHelpDefaultValue(schema.defaultValue)})`));
192
+ if (schema.configPath !== void 0) parts.push(theme.annotation(`[config: ${schema.configPath}]`));
193
+ if (schema.prompt !== void 0) parts.push(theme.annotation("[prompt]"));
194
+ if (schema.presence === "defaulted" || schema.defaultValue !== void 0) parts.push(theme.defaultValue(`(default: ${formatHelpDefaultValue(schema.defaultValue)})`));
172
195
  return parts.join(" ");
173
196
  }
174
197
  /**
@@ -44,25 +44,5 @@ interface HelpTheme {
44
44
  * unconditionally, gating is the framework's job.
45
45
  */
46
46
  type HelpThemeFactory = (colors: Colors) => Partial<HelpTheme>;
47
- /**
48
- * The built-in help theme (clap/cargo conventions).
49
- *
50
- * @param c - Palette to build formatters from (typically the gated `out.color`).
51
- * @internal
52
- */
53
- declare function defaultHelpTheme(c: Colors): HelpTheme;
54
- /**
55
- * Resolve the effective help theme from a palette and optional user factory.
56
- *
57
- * When the palette renders no styling (color disabled — its formatters are
58
- * identity functions), the user factory is **never invoked**: even a factory
59
- * that emits raw escapes cannot leak them into color-off output. When color
60
- * is enabled, factory overrides merge over {@linkcode defaultHelpTheme}.
61
- *
62
- * @param colors - Gated palette, or `undefined` for a color-off theme.
63
- * @param theme - Optional user overrides factory.
64
- * @internal
65
- */
66
- declare function resolveHelpTheme(colors: Colors | undefined, theme: HelpThemeFactory | undefined): HelpTheme;
67
47
  //#endregion
68
- export { type HelpTheme, type HelpThemeFactory, defaultHelpTheme, resolveHelpTheme };
48
+ export type { HelpTheme, HelpThemeFactory };