@kjanat/dreamcli 3.0.0-rc.3 → 3.0.0-rc.6

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.
package/CHANGELOG.md CHANGED
@@ -7,6 +7,51 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [3.0.0-rc.6] - 2026-07-09
11
+
12
+ ### Added
13
+
14
+ - **Runtime terminal sizing hooks** — `RuntimeAdapter` now exposes
15
+ `getTerminalSize()` and `onTerminalResize()`. Node/Bun read
16
+ `process.stdout.getWindowSize()` (falling back to `columns` / `rows`) and
17
+ subscribe to stdout `resize`; Deno uses native `Deno.consoleSize()` and
18
+ `SIGWINCH` on non-Windows platforms.
19
+
20
+ ### Changed
21
+
22
+ - **Help output now fits the live terminal in `.run()`** — root and command help
23
+ use runtime terminal columns when no explicit `.help({ width })` or runtime
24
+ `help.width` is provided. Non-TTY or unavailable sizes still fall back to 80,
25
+ and `.execute()` remains deterministic for tests.
26
+
27
+ ## [3.0.0-rc.5] - 2026-07-08
28
+
29
+ ### Removed
30
+
31
+ - **`createBunAdapter` export** (from `@kjanat/dreamcli/runtime`). Bun exposes a
32
+ Node-compatible `process`, so the Bun adapter had been a pure passthrough to
33
+ the Node adapter since the runtime version hard-fail was dropped — it blessed
34
+ a runtime rather than abstracting distinct I/O. Auto-detection now maps Bun to
35
+ the Node adapter directly and `src/runtime/bun.ts` is gone. Runtime detection
36
+ is unchanged: `detectRuntime()` still reports `'bun'` and `RUNTIMES` still
37
+ lists it. Callers that selected the Bun adapter explicitly should use
38
+ `createNodeAdapter` (identical behavior) or rely on `createAdapter()`
39
+ auto-detection (#51).
40
+
41
+ ## [3.0.0-rc.4] - 2026-07-06
42
+
43
+ ### Added
44
+
45
+ - **`.default(cmd, { route: true })`** — expose a default command under its own
46
+ name as a routable top-level command, in addition to the bare/flags-only root
47
+ surface. `mycli` and `mycli <name>` then run the same command object, and it
48
+ is listed in the root `Commands:` section (tagged `(default)`) beside its
49
+ siblings. Lets CLIs keep both a short root shorthand and an explicit,
50
+ documented named command without duplicating the builder (#55). Opt-in only
51
+ — the surface-only default remains the default behavior. With `route: true`
52
+ the name wins over positional interpretation, so a positional value equal to
53
+ the command's own name must be passed after `--`.
54
+
10
55
  ## [3.0.0-rc.3] - 2026-07-06
11
56
 
12
57
  ### Added
@@ -1038,7 +1083,10 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
1038
1083
  - MIT License.
1039
1084
  - Markdownlint configuration.
1040
1085
 
1041
- [Unreleased]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.3...HEAD
1086
+ [Unreleased]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.6...HEAD
1087
+ [3.0.0-rc.6]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.5...v3.0.0-rc.6
1088
+ [3.0.0-rc.5]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.4...v3.0.0-rc.5
1089
+ [3.0.0-rc.4]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.3...v3.0.0-rc.4
1042
1090
  [3.0.0-rc.3]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.2...v3.0.0-rc.3
1043
1091
  [3.0.0-rc.2]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.1...v3.0.0-rc.2
1044
1092
  [3.0.0-rc.1]: https://github.com/kjanat/dreamcli/compare/v2.5.0...v3.0.0-rc.1
@@ -43,6 +43,15 @@ interface CLISchema {
43
43
  * Set via the {@linkcode CLIBuilder.default | .default()} builder method.
44
44
  */
45
45
  readonly defaultCommand: ErasedCommand | undefined;
46
+ /**
47
+ * Whether the default command is also exposed as a named top-level route.
48
+ *
49
+ * Set by `.default(cmd, { route: true })`. When `true`, `mycli <name>`
50
+ * dispatches to the default command (in addition to the bare/flags-only root
51
+ * surface behavior) and the command is listed in the root `Commands:`
52
+ * section. When `false` (the default), the default is the root surface only.
53
+ */
54
+ readonly defaultCommandRouted: boolean;
46
55
  /**
47
56
  * Config discovery settings.
48
57
  *
@@ -241,6 +250,29 @@ interface CLIRunOptions extends Omit<RunOptions, 'meta' | 'mergedSchema'> {
241
250
  */
242
251
  readonly adapter?: RuntimeAdapter;
243
252
  }
253
+ /**
254
+ * Options for {@linkcode CLIBuilder.default | .default()}.
255
+ */
256
+ interface DefaultCommandOptions {
257
+ /**
258
+ * Also expose the default command under its own name as a routable
259
+ * top-level command.
260
+ *
261
+ * By default a default command is the root *surface* only — `mycli` (bare or
262
+ * flags-only) runs it, but `mycli <its-name>` does not route to it (the token
263
+ * is consumed as the default's first positional). Set `route: true` for CLIs
264
+ * that intentionally expose both forms: `mycli` and `mycli <its-name>` become
265
+ * the same command, and it is listed in the root `Commands:` section beside
266
+ * its siblings.
267
+ *
268
+ * The name wins over positional interpretation: with `route: true`, a
269
+ * positional value equal to the command's own name is consumed as the route,
270
+ * so pass such a value after `--` (`mycli -- <name>`).
271
+ *
272
+ * @defaultValue `false`
273
+ */
274
+ readonly route?: boolean;
275
+ }
244
276
  /**
245
277
  * Immutable CLI program builder.
246
278
  *
@@ -543,10 +575,17 @@ declare class CLIBuilder {
543
575
  * this command instead of showing root help.
544
576
  *
545
577
  * The default command is the CLI's root *surface*: its flags and arguments
546
- * are rendered inline in root help. It is **not** a named subcommand — it
547
- * cannot be invoked by its own name (`mycli mycmd` does not route to it) and
548
- * it is omitted from the root `Commands:` list by default (re-enable with
549
- * `.help({ showDefaultInCommands: true })`). Only one default is allowed.
578
+ * are rendered inline in root help. By default it is **not** a named
579
+ * subcommand — it cannot be invoked by its own name (`mycli mycmd` does not
580
+ * route to it) and it is omitted from the root `Commands:` list (re-enable
581
+ * listing with `.help({ showDefaultInCommands: true })`). Only one default is
582
+ * allowed.
583
+ *
584
+ * Pass `{ route: true }` to *also* expose the command under its own name as a
585
+ * routable top-level command: `mycli` and `mycli <name>` then run the same
586
+ * command object, and it is listed in `Commands:` beside its siblings. This
587
+ * avoids duplicating the command just to keep both forms equivalent during a
588
+ * v3 migration.
550
589
  *
551
590
  * @example
552
591
  * ```ts
@@ -563,12 +602,21 @@ declare class CLIBuilder {
563
602
  * .default(deploy)
564
603
  * .command(status)
565
604
  * .run();
605
+ *
606
+ * // Default that is also a named route — `mytool` and `mytool status` are
607
+ * // the same surface, and `status` is listed beside `logs`:
608
+ * cli('mytool')
609
+ * .default(status, { route: true })
610
+ * .command(logs)
611
+ * .run();
566
612
  * ```
567
613
  *
568
614
  * @param cmd - {@link CommandBuilder} to register as the default.
615
+ * @param options - Default-command options. `{ route: true }` also exposes
616
+ * the command under its own name (see {@link DefaultCommandOptions}).
569
617
  * @returns The builder (for chaining).
570
618
  */
571
- default<F extends Record<string, FlagBuilder<FlagConfig>>, A extends Record<string, ArgBuilder<ArgConfig>>, C extends Record<string, unknown>>(cmd: CommandBuilder<F, A, C>): CLIBuilder;
619
+ default<F extends Record<string, FlagBuilder<FlagConfig>>, A extends Record<string, ArgBuilder<ArgConfig>>, C extends Record<string, unknown>>(cmd: CommandBuilder<F, A, C>, options?: DefaultCommandOptions): CLIBuilder;
572
620
  /**
573
621
  * Register a CLI plugin.
574
622
  *
@@ -730,4 +778,4 @@ declare function cli(name: string): CLIBuilder;
730
778
  /** Create a new CLI program builder from an options object. */
731
779
  declare function cli(options: CLIOptions): CLIBuilder;
732
780
  //#endregion
733
- export { type BeforeParseParams, CLIBuilder, type CLIOptions, type CLIPlugin, type CLIPluginHooks, type CLIRunOptions, type CLISchema, type CompletionsFlagConfig, type ConfigSettings, type HelpConfig, type HelpLinks, type InferNameOption, type ManifestPresetSettings, type ManifestSettings, type PackageJsonSettings, type PluginCommandContext, type ResolvedCommandParams, type ResolvedManifestSettings, cli, formatRootHelp, plugin };
781
+ export { type BeforeParseParams, CLIBuilder, type CLIOptions, type CLIPlugin, type CLIPluginHooks, type CLIRunOptions, type CLISchema, type CompletionsFlagConfig, type ConfigSettings, type DefaultCommandOptions, type HelpConfig, type HelpLinks, type InferNameOption, type ManifestPresetSettings, type ManifestSettings, type PackageJsonSettings, type PluginCommandContext, type ResolvedCommandParams, type ResolvedManifestSettings, cli, formatRootHelp, plugin };
@@ -375,10 +375,17 @@ var CLIBuilder = class CLIBuilder {
375
375
  * this command instead of showing root help.
376
376
  *
377
377
  * The default command is the CLI's root *surface*: its flags and arguments
378
- * are rendered inline in root help. It is **not** a named subcommand — it
379
- * cannot be invoked by its own name (`mycli mycmd` does not route to it) and
380
- * it is omitted from the root `Commands:` list by default (re-enable with
381
- * `.help({ showDefaultInCommands: true })`). Only one default is allowed.
378
+ * are rendered inline in root help. By default it is **not** a named
379
+ * subcommand — it cannot be invoked by its own name (`mycli mycmd` does not
380
+ * route to it) and it is omitted from the root `Commands:` list (re-enable
381
+ * listing with `.help({ showDefaultInCommands: true })`). Only one default is
382
+ * allowed.
383
+ *
384
+ * Pass `{ route: true }` to *also* expose the command under its own name as a
385
+ * routable top-level command: `mycli` and `mycli <name>` then run the same
386
+ * command object, and it is listed in `Commands:` beside its siblings. This
387
+ * avoids duplicating the command just to keep both forms equivalent during a
388
+ * v3 migration.
382
389
  *
383
390
  * @example
384
391
  * ```ts
@@ -395,12 +402,21 @@ var CLIBuilder = class CLIBuilder {
395
402
  * .default(deploy)
396
403
  * .command(status)
397
404
  * .run();
405
+ *
406
+ * // Default that is also a named route — `mytool` and `mytool status` are
407
+ * // the same surface, and `status` is listed beside `logs`:
408
+ * cli('mytool')
409
+ * .default(status, { route: true })
410
+ * .command(logs)
411
+ * .run();
398
412
  * ```
399
413
  *
400
414
  * @param cmd - {@link CommandBuilder} to register as the default.
415
+ * @param options - Default-command options. `{ route: true }` also exposes
416
+ * the command under its own name (see {@link DefaultCommandOptions}).
401
417
  * @returns The builder (for chaining).
402
418
  */
403
- default(cmd) {
419
+ default(cmd, options) {
404
420
  if (this.schema.defaultCommand !== void 0) throw new CLIError("Only one default command is allowed", {
405
421
  code: "DUPLICATE_DEFAULT",
406
422
  suggest: "Call .default() only once when building the CLI"
@@ -410,7 +426,8 @@ var CLIBuilder = class CLIBuilder {
410
426
  const erased = eraseCommand(cmd);
411
427
  return new CLIBuilder({
412
428
  ...this.schema,
413
- defaultCommand: erased
429
+ defaultCommand: erased,
430
+ defaultCommandRouted: options?.route ?? false
414
431
  });
415
432
  }
416
433
  /**
@@ -667,9 +684,16 @@ var CLIBuilder = class CLIBuilder {
667
684
  return adapter.exit(preflight.error.exitCode);
668
685
  }
669
686
  const effectiveBuilder = preflight.schema === this.schema ? this : new CLIBuilder(preflight.schema);
687
+ const terminalSize = adapter.getTerminalSize();
688
+ const runtimeHelpWidth = options?.help?.width === void 0 && preflight.schema.helpConfig?.width === void 0 ? terminalSize?.columns : void 0;
689
+ const runtimeHelpOptions = runtimeHelpWidth !== void 0 ? {
690
+ ...options?.help,
691
+ width: runtimeHelpWidth
692
+ } : options?.help;
670
693
  const executeOptions = {
671
694
  ...options,
672
695
  ...preflight.inputs,
696
+ ...runtimeHelpOptions !== void 0 ? { help: runtimeHelpOptions } : {},
673
697
  out: createOutput({
674
698
  stdout: adapter.stdout,
675
699
  stderr: adapter.stderr,
@@ -888,6 +912,7 @@ function cli(nameOrOptions) {
888
912
  description: void 0,
889
913
  commands: [],
890
914
  defaultCommand: void 0,
915
+ defaultCommandRouted: false,
891
916
  configSettings: void 0,
892
917
  packageJsonSettings: void 0,
893
918
  helpLinks: void 0,
@@ -23,6 +23,8 @@ interface PlannerSchemaLike {
23
23
  readonly commands: readonly ErasedCommand[];
24
24
  /** Fallback command when no subcommand token matches. */
25
25
  readonly defaultCommand: ErasedCommand | undefined;
26
+ /** Whether the default command is also exposed as a named top-level route. */
27
+ readonly defaultCommandRouted: boolean;
26
28
  /**
27
29
  * Eager `--completions <shell>` flag configuration, when `.completions()`
28
30
  * was registered with `{ as: 'flag' }`. `undefined` disables interception.
@@ -243,7 +243,7 @@ function planInvocation(options) {
243
243
  kind: "root-help",
244
244
  help: options.help
245
245
  };
246
- const result = dispatch(filteredArgv, buildRootCommandMap(options.schema.commands), [], rootValueFlags);
246
+ const result = dispatch(filteredArgv, buildRootCommandMap(defaultCommand !== void 0 && options.schema.defaultCommandRouted ? [...options.schema.commands, defaultCommand] : options.schema.commands), [], rootValueFlags);
247
247
  switch (result.kind) {
248
248
  case "unknown": {
249
249
  if (defaultCommand !== void 0 && result.parentPath.length === 0) {
@@ -13,6 +13,8 @@ interface CLISchemaLike {
13
13
  readonly defaultCommand: {
14
14
  readonly schema: CommandSchema;
15
15
  } | undefined;
16
+ /** Whether the default is also a named route — listed in `Commands:` when so. */
17
+ readonly defaultCommandRouted?: boolean | undefined;
16
18
  readonly helpLinks?: {
17
19
  readonly name: string | undefined;
18
20
  readonly version: string | undefined;
@@ -49,8 +49,9 @@ function formatRootHelp(schema, options) {
49
49
  const surfaceUsage = surfaceSections.shift();
50
50
  if (inline && surfaceUsage !== void 0 && inlineDefaultCommand !== void 0) sections.push(surface.hasVisibleSubcommands ? mergeUsageSections(rootUsage, surfaceUsage) : surfaceUsage);
51
51
  else sections.push(rootUsage);
52
- const listedCommands = showDefaultInCommands && defaultCommand !== void 0 ? [...surface.visibleSubcommands, defaultCommand] : surface.visibleSubcommands;
53
- if (listedCommands.length > 0) sections.push(formatRootCommandsSection(listedCommands, showDefaultInCommands ? defaultCommand?.name : void 0, width));
52
+ const listDefaultInCommands = defaultCommand !== void 0 && (surface.defaultRouted || showDefaultInCommands);
53
+ const listedCommands = listDefaultInCommands ? [...surface.visibleSubcommands, defaultCommand] : surface.visibleSubcommands;
54
+ if (listedCommands.length > 0) sections.push(formatRootCommandsSection(listedCommands, listDefaultInCommands ? defaultCommand?.name : void 0, width));
54
55
  if (inline && surfaceCommand !== void 0) {
55
56
  if (surfaceCommand.description !== void 0 && surfaceCommand.description === schema.description && surfaceSections[0] === surfaceCommand.description) surfaceSections.shift();
56
57
  sections.push(...surfaceSections);
@@ -16,6 +16,12 @@ interface RootSurfaceSchemaLike {
16
16
  readonly defaultCommand: {
17
17
  readonly schema: CommandSchema;
18
18
  } | undefined;
19
+ /**
20
+ * Whether the default command is also exposed as a named route
21
+ * (`.default(cmd, { route: true })`). Optional so hand-built schema-like
22
+ * objects default to the surface-only behavior.
23
+ */
24
+ readonly defaultCommandRouted?: boolean | undefined;
19
25
  }
20
26
  /**
21
27
  * Normalized root shape shared by help and completion logic.
@@ -40,6 +46,12 @@ interface RootSurface {
40
46
  readonly hasVisibleDefault: boolean;
41
47
  /** Whether any visible real subcommands exist (the default does not count). */
42
48
  readonly hasVisibleSubcommands: boolean;
49
+ /**
50
+ * Whether the visible default is also a named route (`.default(cmd, { route:
51
+ * true })`), meaning it should be listed in `Commands:` beside its siblings
52
+ * in addition to being rendered as the root surface.
53
+ */
54
+ readonly defaultRouted: boolean;
43
55
  }
44
56
  /**
45
57
  * Resolve the visible shape of the CLI root.
@@ -20,7 +20,8 @@ function resolveRootSurface(schema) {
20
20
  visibleSubcommands,
21
21
  visibleDefaultCommand,
22
22
  hasVisibleDefault: visibleDefaultCommand !== void 0,
23
- hasVisibleSubcommands: visibleSubcommands.length > 0
23
+ hasVisibleSubcommands: visibleSubcommands.length > 0,
24
+ defaultRouted: visibleDefaultCommand !== void 0 && schema.defaultCommandRouted === true
24
25
  };
25
26
  }
26
27
  //#endregion
@@ -58,6 +58,8 @@ interface RuntimePreflightSchemaLike {
58
58
  readonly commands: readonly ErasedCommand[];
59
59
  /** Fallback command when no subcommand token matches. */
60
60
  readonly defaultCommand: ErasedCommand | undefined;
61
+ /** Whether the default command is also exposed as a named top-level route. */
62
+ readonly defaultCommandRouted: boolean;
61
63
  /** Config file discovery settings; `undefined` disables config loading. */
62
64
  readonly configSettings: RuntimeConfigSettings | undefined;
63
65
  /** Package.json discovery settings; `undefined` disables package.json inference. */
package/dist/index.d.mts CHANGED
@@ -26,7 +26,7 @@ import { generatePowerShellCompletion } from "./core/completion/shells/powershel
26
26
  import { generateZshCompletion } from "./core/completion/shells/zsh.mjs";
27
27
  import { SHELLS, Shell, generateCompletion } from "./core/completion/index.mjs";
28
28
  import { ConfigAdapter, ConfigDiscoveryOptions, ConfigDiscoveryResult, ConfigFound, ConfigNotFound, FormatLoader, buildConfigSearchPaths, configFormat, discoverConfig } from "./core/config/index.mjs";
29
- import { CLIBuilder, CLIOptions, CLIRunOptions, CLISchema, ConfigSettings, InferNameOption, ManifestPresetSettings, ManifestSettings, PackageJsonSettings, ResolvedManifestSettings, cli } from "./core/cli/index.mjs";
29
+ import { CLIBuilder, CLIOptions, CLIRunOptions, CLISchema, ConfigSettings, DefaultCommandOptions, InferNameOption, ManifestPresetSettings, ManifestSettings, PackageJsonSettings, ResolvedManifestSettings, cli } from "./core/cli/index.mjs";
30
30
  import { JsonSchemaOptions, definitionMetaSchema, generateInputSchema, generateSchema } from "./core/json-schema/index.mjs";
31
31
  import { Colors } from "ansispeck";
32
- export { type ActionHandler, type ActionParams, type ActivityEvent, type AnyCommandBuilder, ArgBuilder, type ArgConfig, type ArgFactory, type ArgKind, type ArgParseFn, type ArgPresence, type ArgSchema, type BeforeParseParams, CLIBuilder, CLIError, type CLIErrorJSON, type CLIErrorOptions, type CLIOptions, type CLIPlugin, type CLIPluginHooks, type CLIRunOptions, type CLISchema, type Colors, type CommandArgEntry, CommandBuilder, type CommandConfig, type CommandExample, type CommandMeta, type CommandSchema, type CompletionOptions, type ConfigAdapter, type ConfigDiscoveryOptions, type ConfigDiscoveryResult, type ConfigFound, type ConfigNotFound, type ConfigSettings, type ConfirmPromptConfig, type DeprecationWarning, type DeriveHandler, type DeriveParams, type ErrorCode, type Fallback, FlagBuilder, type FlagConfig, type FlagFactory, type FlagKind, type FlagParseFn, type FlagPresence, type FlagSchema, type FormatLoader, type HelpLinks, type HelpOptions, type InferArg, type InferArgs, type InferFlag, type InferFlags, type InferNameOption, type InputPromptConfig, type InteractiveParams, type InteractiveResolver, type InteractiveResult, type JsonSchemaOptions, type ManifestDiscoveryOptions, type ManifestPresetSettings, type ManifestSettings, type Middleware, type MiddlewareHandler, type MiddlewareParams, type MultiselectPromptConfig, type NumberConstraintViolation, type NumberConstraints, type Out, type OutputOptions, type PackageJsonAdapter, type PackageJsonData, type PackageJsonSettings, type PackageRepository, ParseError, type ParseErrorCode, type ParseErrorOptions, type ParseResult, type PluginCommandContext, type ProgressHandle, type ProgressOptions, type PromptConfig, type PromptConfigBase, type PromptEngine, type PromptKind, type PromptResult, type ReadFn, type ResolveOptions, type ResolveResult, type ResolvedArgValue, type ResolvedCommandParams, type ResolvedManifestSettings, type ResolvedMultiselectPromptConfig, type ResolvedPromptConfig, type ResolvedSelectPromptConfig, type ResolvedValue, type RunResult, SHELLS, type SelectChoice, type SelectPromptConfig, type Shell, type SpinnerHandle, type SpinnerOptions, type TableColumn, type TableFormat, type TableOptions, type TableStream, type Token, ValidationError, type ValidationErrorCode, type ValidationErrorOptions, type Verbosity, type WithArgPresence, type WithPresence, type WithVariadic, type WriteFn, arg, buildConfigSearchPaths, cli, command, configFormat, createArgSchema, createOutput, createSchema, createTerminalPrompter, definitionMetaSchema, discoverConfig, discoverManifest, discoverPackageJson, flag, formatHelp, generateBashCompletion, generateCompletion, generateFishCompletion, generateInputSchema, generatePowerShellCompletion, generateSchema, generateZshCompletion, group, inferCliName, isCLIError, isParseError, isValidationError, middleware, osc8, packageRepositoryUrl, parse, plugin, resolve, resolvePromptConfig, tokenize, visibleWidth };
32
+ export { type ActionHandler, type ActionParams, type ActivityEvent, type AnyCommandBuilder, ArgBuilder, type ArgConfig, type ArgFactory, type ArgKind, type ArgParseFn, type ArgPresence, type ArgSchema, type BeforeParseParams, CLIBuilder, CLIError, type CLIErrorJSON, type CLIErrorOptions, type CLIOptions, type CLIPlugin, type CLIPluginHooks, type CLIRunOptions, type CLISchema, type Colors, type CommandArgEntry, CommandBuilder, type CommandConfig, type CommandExample, type CommandMeta, type CommandSchema, type CompletionOptions, type ConfigAdapter, type ConfigDiscoveryOptions, type ConfigDiscoveryResult, type ConfigFound, type ConfigNotFound, type ConfigSettings, type ConfirmPromptConfig, type DefaultCommandOptions, type DeprecationWarning, type DeriveHandler, type DeriveParams, type ErrorCode, type Fallback, FlagBuilder, type FlagConfig, type FlagFactory, type FlagKind, type FlagParseFn, type FlagPresence, type FlagSchema, type FormatLoader, type HelpLinks, type HelpOptions, type InferArg, type InferArgs, type InferFlag, type InferFlags, type InferNameOption, type InputPromptConfig, type InteractiveParams, type InteractiveResolver, type InteractiveResult, type JsonSchemaOptions, type ManifestDiscoveryOptions, type ManifestPresetSettings, type ManifestSettings, type Middleware, type MiddlewareHandler, type MiddlewareParams, type MultiselectPromptConfig, type NumberConstraintViolation, type NumberConstraints, type Out, type OutputOptions, type PackageJsonAdapter, type PackageJsonData, type PackageJsonSettings, type PackageRepository, ParseError, type ParseErrorCode, type ParseErrorOptions, type ParseResult, type PluginCommandContext, type ProgressHandle, type ProgressOptions, type PromptConfig, type PromptConfigBase, type PromptEngine, type PromptKind, type PromptResult, type ReadFn, type ResolveOptions, type ResolveResult, type ResolvedArgValue, type ResolvedCommandParams, type ResolvedManifestSettings, type ResolvedMultiselectPromptConfig, type ResolvedPromptConfig, type ResolvedSelectPromptConfig, type ResolvedValue, type RunResult, SHELLS, type SelectChoice, type SelectPromptConfig, type Shell, type SpinnerHandle, type SpinnerOptions, type TableColumn, type TableFormat, type TableOptions, type TableStream, type Token, ValidationError, type ValidationErrorCode, type ValidationErrorOptions, type Verbosity, type WithArgPresence, type WithPresence, type WithVariadic, type WriteFn, arg, buildConfigSearchPaths, cli, command, configFormat, createArgSchema, createOutput, createSchema, createTerminalPrompter, definitionMetaSchema, discoverConfig, discoverManifest, discoverPackageJson, flag, formatHelp, generateBashCompletion, generateCompletion, generateFishCompletion, generateInputSchema, generatePowerShellCompletion, generateSchema, generateZshCompletion, group, inferCliName, isCLIError, isParseError, isValidationError, middleware, osc8, packageRepositoryUrl, parse, plugin, resolve, resolvePromptConfig, tokenize, visibleWidth };
@@ -62,6 +62,10 @@ interface RuntimeAdapter {
62
62
  readonly isTTY: boolean;
63
63
  /** Whether stdin is connected to a TTY (used for prompt gating). */
64
64
  readonly stdinIsTTY: boolean;
65
+ /** Read current terminal dimensions for stdout, if available. */
66
+ readonly getTerminalSize: () => TerminalSize | undefined;
67
+ /** Subscribe to terminal resize events when the runtime supports them. */
68
+ readonly onTerminalResize: (listener: () => void) => (() => void) | undefined;
65
69
  /**
66
70
  * Exit the process with the given code.
67
71
  * Must not return (divergent function).
@@ -95,6 +99,13 @@ interface RuntimeAdapter {
95
99
  */
96
100
  readonly configDir: string;
97
101
  }
102
+ /** Current terminal dimensions in columns and rows. */
103
+ interface TerminalSize {
104
+ /** Terminal width in columns. */
105
+ readonly columns: number;
106
+ /** Terminal height in rows. */
107
+ readonly rows: number;
108
+ }
98
109
  /**
99
110
  * Options for creating a test adapter.
100
111
  *
@@ -138,6 +149,10 @@ interface TestAdapterOptions {
138
149
  readonly isTTY?: boolean;
139
150
  /** TTY flag for stdin (defaults to `false`). */
140
151
  readonly stdinIsTTY?: boolean;
152
+ /** Terminal dimensions returned by `getTerminalSize()`. */
153
+ readonly terminalSize?: TerminalSize;
154
+ /** Resize subscription hook returned by `onTerminalResize()`. */
155
+ readonly onTerminalResize?: (listener: () => void) => (() => void) | undefined;
141
156
  /**
142
157
  * Exit function (defaults to throwing {@linkcode ExitError}).
143
158
  * The default throw-based exit allows tests to catch the exit code.
@@ -209,4 +224,4 @@ declare class ExitError extends Error {
209
224
  */
210
225
  declare function createTestAdapter(options?: TestAdapterOptions): RuntimeAdapter;
211
226
  //#endregion
212
- export { ExitError, type RuntimeAdapter, type TestAdapterOptions, createTestAdapter };
227
+ export { ExitError, type RuntimeAdapter, type TerminalSize, type TestAdapterOptions, createTestAdapter };
@@ -70,6 +70,8 @@ function createTestAdapter(options) {
70
70
  },
71
71
  isTTY: options?.isTTY ?? false,
72
72
  stdinIsTTY,
73
+ getTerminalSize: () => options?.terminalSize,
74
+ onTerminalResize: (listener) => options?.onTerminalResize?.(listener),
73
75
  exit: options?.exit ?? ((code) => {
74
76
  throw new ExitError(code);
75
77
  }),
@@ -6,8 +6,8 @@ import { GlobalForDetect } from "./detect.mjs";
6
6
  * Create a runtime adapter for the current environment.
7
7
  *
8
8
  * Detection order follows {@link detectRuntime}: Bun → Deno → Node → unknown.
9
- * Unknown runtimes fall back to the Node adapter because most JS runtimes
10
- * expose a Node-compatible `process` global.
9
+ * Only Deno needs a distinct adapter; Bun, Node, and unknown runtimes all use
10
+ * the Node adapter because they expose a Node-compatible `process` global.
11
11
  *
12
12
  * @param globals - Override `globalThis` for testing. Production callers
13
13
  * should omit this parameter.
@@ -1,7 +1,6 @@
1
- import { createNodeAdapter } from "./node.mjs";
2
- import { createBunAdapter } from "./bun.mjs";
3
1
  import { createDenoAdapter } from "./deno.mjs";
4
2
  import { detectRuntime } from "./detect.mjs";
3
+ import { createNodeAdapter } from "./node.mjs";
5
4
  //#region src/runtime/auto.ts
6
5
  function isDenoNamespace(value) {
7
6
  if (typeof value !== "object" || value === null) return false;
@@ -16,8 +15,8 @@ function getInjectedDenoNamespace(globals) {
16
15
  * Create a runtime adapter for the current environment.
17
16
  *
18
17
  * Detection order follows {@link detectRuntime}: Bun → Deno → Node → unknown.
19
- * Unknown runtimes fall back to the Node adapter because most JS runtimes
20
- * expose a Node-compatible `process` global.
18
+ * Only Deno needs a distinct adapter; Bun, Node, and unknown runtimes all use
19
+ * the Node adapter because they expose a Node-compatible `process` global.
21
20
  *
22
21
  * @param globals - Override `globalThis` for testing. Production callers
23
22
  * should omit this parameter.
@@ -35,8 +34,8 @@ function createAdapter(globals) {
35
34
  const runtimeGlobals = globals ?? globalThis;
36
35
  const runtime = detectRuntime(runtimeGlobals);
37
36
  switch (runtime) {
38
- case "bun": return createBunAdapter();
39
37
  case "deno": return createDenoAdapter(getInjectedDenoNamespace(runtimeGlobals));
38
+ case "bun":
40
39
  case "node":
41
40
  case "unknown": return createNodeAdapter();
42
41
  default: return runtime;
@@ -34,6 +34,15 @@ interface DenoNamespace {
34
34
  /** Write raw bytes to stdout synchronously. */writeSync(p: Uint8Array): number; /** Whether stdout is connected to a TTY. */
35
35
  isTerminal(): boolean;
36
36
  };
37
+ /** Current console dimensions. */
38
+ consoleSize?(): {
39
+ readonly columns: number;
40
+ readonly rows: number;
41
+ };
42
+ /** Register a native signal listener. */
43
+ addSignalListener?(signal: 'SIGWINCH', listener: () => void): void;
44
+ /** Remove a native signal listener. */
45
+ removeSignalListener?(signal: 'SIGWINCH', listener: () => void): void;
37
46
  /** Standard error — synchronous byte writer. */
38
47
  readonly stderr: {
39
48
  /** Write raw bytes to stderr synchronously. */writeSync(p: Uint8Array): number;
@@ -100,12 +100,48 @@ function createDenoAdapter(ns) {
100
100
  readStdin: () => readDenoStdinAll(d, stdinIsTTY),
101
101
  isTTY: d.stdout.isTerminal(),
102
102
  stdinIsTTY,
103
+ getTerminalSize: () => readDenoTerminalSize(d),
104
+ onTerminalResize: (listener) => onDenoTerminalResize(d, listener),
103
105
  exit: (code) => d.exit(code),
104
106
  readFile,
105
107
  homedir,
106
108
  configDir
107
109
  };
108
110
  }
111
+ /** Normalize terminal dimensions and discard unusable values. @internal */
112
+ function normalizeTerminalSize(columns, rows) {
113
+ if (columns === void 0 || rows === void 0) return void 0;
114
+ if (!Number.isFinite(columns) || !Number.isFinite(rows)) return void 0;
115
+ if (columns <= 0 || rows <= 0) return void 0;
116
+ return {
117
+ columns,
118
+ rows
119
+ };
120
+ }
121
+ /** Read native Deno terminal dimensions. @internal */
122
+ function readDenoTerminalSize(deno) {
123
+ if (!deno.stdout.isTerminal() || deno.consoleSize === void 0) return void 0;
124
+ try {
125
+ const size = deno.consoleSize();
126
+ return normalizeTerminalSize(size.columns, size.rows);
127
+ } catch {
128
+ return;
129
+ }
130
+ }
131
+ /** Subscribe to native Deno resize signals where SIGWINCH exists. @internal */
132
+ function onDenoTerminalResize(deno, listener) {
133
+ if (!deno.stdout.isTerminal()) return void 0;
134
+ if (deno.build.os === "windows") return void 0;
135
+ if (deno.addSignalListener === void 0 || deno.removeSignalListener === void 0) return;
136
+ try {
137
+ deno.addSignalListener("SIGWINCH", listener);
138
+ } catch {
139
+ return;
140
+ }
141
+ return () => {
142
+ deno.removeSignalListener?.("SIGWINCH", listener);
143
+ };
144
+ }
109
145
  /**
110
146
  * Access the global `Deno` namespace.
111
147
  *
@@ -1,7 +1,6 @@
1
- import { ExitError, RuntimeAdapter, TestAdapterOptions, createTestAdapter } from "./adapter.mjs";
1
+ import { ExitError, RuntimeAdapter, TerminalSize, TestAdapterOptions, createTestAdapter } from "./adapter.mjs";
2
2
  import { GlobalForDetect, RUNTIMES, Runtime, detectRuntime } from "./detect.mjs";
3
3
  import { createAdapter } from "./auto.mjs";
4
- import { NodeProcess, createNodeAdapter } from "./node.mjs";
5
- import { createBunAdapter } from "./bun.mjs";
6
4
  import { DenoNamespace, createDenoAdapter } from "./deno.mjs";
7
- export { type DenoNamespace, ExitError, type GlobalForDetect, type NodeProcess, RUNTIMES, type Runtime, type RuntimeAdapter, type TestAdapterOptions, createAdapter, createBunAdapter, createDenoAdapter, createNodeAdapter, createTestAdapter, detectRuntime };
5
+ import { NodeProcess, createNodeAdapter } from "./node.mjs";
6
+ export { type DenoNamespace, ExitError, type GlobalForDetect, type NodeProcess, RUNTIMES, type Runtime, type RuntimeAdapter, type TerminalSize, type TestAdapterOptions, createAdapter, createDenoAdapter, createNodeAdapter, createTestAdapter, detectRuntime };
@@ -30,6 +30,12 @@ interface NodeProcess {
30
30
  /** Standard output stream with TTY detection and write. */
31
31
  readonly stdout: {
32
32
  readonly isTTY?: boolean;
33
+ readonly columns?: number;
34
+ readonly rows?: number;
35
+ getWindowSize?(): readonly [number, number];
36
+ on?(event: 'resize', listener: () => void): unknown;
37
+ off?(event: 'resize', listener: () => void): unknown;
38
+ removeListener?(event: 'resize', listener: () => void): unknown;
33
39
  write(data: string): unknown;
34
40
  };
35
41
  /** Standard error stream with write. */
@@ -103,12 +103,53 @@ function createNodeAdapter(proc) {
103
103
  readStdin: () => readNodeStdinAll(p, stdinIsTTY),
104
104
  isTTY: p.stdout.isTTY === true,
105
105
  stdinIsTTY,
106
+ getTerminalSize: () => readNodeTerminalSize(p),
107
+ onTerminalResize: (listener) => onNodeTerminalResize(p, listener),
106
108
  exit: (code) => p.exit(code),
107
109
  readFile,
108
110
  homedir,
109
111
  configDir
110
112
  };
111
113
  }
114
+ /** Normalize terminal dimensions and discard unusable values. @internal */
115
+ function normalizeTerminalSize(columns, rows) {
116
+ if (columns === void 0 || rows === void 0) return void 0;
117
+ if (!Number.isFinite(columns) || !Number.isFinite(rows)) return void 0;
118
+ if (columns <= 0 || rows <= 0) return void 0;
119
+ return {
120
+ columns,
121
+ rows
122
+ };
123
+ }
124
+ /** Read Node/Bun terminal dimensions from stdout. @internal */
125
+ function readNodeTerminalSize(proc) {
126
+ if (proc.stdout.isTTY !== true) return void 0;
127
+ try {
128
+ const size = proc.stdout.getWindowSize?.();
129
+ if (size !== void 0) {
130
+ const [columns, rows] = size;
131
+ const normalized = normalizeTerminalSize(columns, rows);
132
+ if (normalized !== void 0) return normalized;
133
+ }
134
+ } catch {}
135
+ return normalizeTerminalSize(proc.stdout.columns, proc.stdout.rows);
136
+ }
137
+ /** Subscribe to Node/Bun stdout resize events when available. @internal */
138
+ function onNodeTerminalResize(proc, listener) {
139
+ if (proc.stdout.isTTY !== true || proc.stdout.on === void 0) return void 0;
140
+ if (proc.stdout.off !== void 0) {
141
+ proc.stdout.on("resize", listener);
142
+ return () => {
143
+ proc.stdout.off?.("resize", listener);
144
+ };
145
+ }
146
+ if (proc.stdout.removeListener !== void 0) {
147
+ proc.stdout.on("resize", listener);
148
+ return () => {
149
+ proc.stdout.removeListener?.("resize", listener);
150
+ };
151
+ }
152
+ }
112
153
  /**
113
154
  * Read all of stdin as a single string (for piped data).
114
155
  *
@@ -1,7 +1,6 @@
1
- import { ExitError, RuntimeAdapter } from "./runtime/adapter.mjs";
1
+ import { ExitError, RuntimeAdapter, TerminalSize } from "./runtime/adapter.mjs";
2
2
  import { RUNTIMES, Runtime, detectRuntime } from "./runtime/detect.mjs";
3
3
  import { createAdapter } from "./runtime/auto.mjs";
4
- import { createNodeAdapter } from "./runtime/node.mjs";
5
- import { createBunAdapter } from "./runtime/bun.mjs";
6
4
  import { createDenoAdapter } from "./runtime/deno.mjs";
7
- export { ExitError, RUNTIMES, type Runtime, type RuntimeAdapter, createAdapter, createBunAdapter, createDenoAdapter, createNodeAdapter, detectRuntime };
5
+ import { createNodeAdapter } from "./runtime/node.mjs";
6
+ export { ExitError, RUNTIMES, type Runtime, type RuntimeAdapter, type TerminalSize, createAdapter, createDenoAdapter, createNodeAdapter, detectRuntime };
package/dist/runtime.mjs CHANGED
@@ -1,7 +1,6 @@
1
- import { createNodeAdapter } from "./runtime/node.mjs";
2
- import { createBunAdapter } from "./runtime/bun.mjs";
3
1
  import { createDenoAdapter } from "./runtime/deno.mjs";
4
2
  import { RUNTIMES, detectRuntime } from "./runtime/detect.mjs";
3
+ import { createNodeAdapter } from "./runtime/node.mjs";
5
4
  import { createAdapter } from "./runtime/auto.mjs";
6
5
  import { ExitError } from "./runtime/adapter.mjs";
7
- export { ExitError, RUNTIMES, createAdapter, createBunAdapter, createDenoAdapter, createNodeAdapter, detectRuntime };
6
+ export { ExitError, RUNTIMES, createAdapter, createDenoAdapter, createNodeAdapter, detectRuntime };
package/dist/version.mjs CHANGED
@@ -1,7 +1,7 @@
1
1
  //#region src/version.ts
2
2
  /** Package version (e.g. `"0.9.1"`). `"dev"` when running unbundled. */
3
- const DREAMCLI_VERSION = "3.0.0-rc.3";
3
+ const DREAMCLI_VERSION = "3.0.0-rc.6";
4
4
  /** Git short SHA (e.g. `"f9b5f1a"`). `"dev"` when running unbundled. */
5
- const DREAMCLI_REVISION = "539c625";
5
+ const DREAMCLI_REVISION = "c63883e";
6
6
  //#endregion
7
7
  export { DREAMCLI_REVISION, DREAMCLI_VERSION };
package/package.json CHANGED
@@ -1,8 +1,16 @@
1
1
  {
2
2
  "name": "@kjanat/dreamcli",
3
- "version": "3.0.0-rc.3",
3
+ "version": "3.0.0-rc.6",
4
4
  "description": "Schema-first, fully typed TypeScript CLI framework",
5
- "keywords": ["dreamcli", "cli", "typescript", "framework", "schema-first", "command-line"],
5
+ "keywords": [
6
+ "dreamcli",
7
+ "cli",
8
+ "typescript",
9
+ "framework",
10
+ "schema-first",
11
+ "command-line",
12
+ "ansispeck"
13
+ ],
6
14
  "homepage": "https://dreamcli.kjanat.dev",
7
15
  "bugs": {
8
16
  "url": "https://github.com/kjanat/dreamcli/issues"
@@ -113,8 +121,8 @@
113
121
  "@types/bun": "^1.3.14",
114
122
  "@types/deno": "^2.7.0",
115
123
  "@types/node": ">=26.1.0",
116
- "@typescript/native-preview": "^7.0.0-dev.20260705.1",
117
- "@vitest/coverage-v8": "^4.1.9",
124
+ "@typescript/native-preview": "^7.0.0-dev.20260706.1",
125
+ "@vitest/coverage-v8": "^4.1.10",
118
126
  "dprint": "^0.55.1",
119
127
  "floating-vue": "^5.2.2",
120
128
  "knip": "^6.24.0",
@@ -122,11 +130,11 @@
122
130
  "publint": "^0.3.21",
123
131
  "runner-run": "0.19.1",
124
132
  "tsdown": "^0.22.3",
125
- "typedoc": "^0.28.19",
133
+ "typedoc": "^0.28.20",
126
134
  "typescript": "^6.0.3",
127
135
  "vite": "^8.1.3",
128
- "vitepress": "^2.0.0-alpha.17",
129
- "vitest": "^4.1.9",
136
+ "vitepress": "^2.0.0-alpha.18",
137
+ "vitest": "^4.1.10",
130
138
  "wrangler": "^4.107.0",
131
139
  "yaml": "^2.9.0"
132
140
  },
@@ -151,8 +159,7 @@
151
159
  "npm": "11.18.0"
152
160
  },
153
161
  "publishConfig": {
154
- "access": "public",
155
- "provenance": true
162
+ "access": "public"
156
163
  },
157
164
  "catalog": {
158
165
  "@types/bun": "^1.3.14",
@@ -1,28 +0,0 @@
1
- import { RuntimeAdapter } from "./adapter.mjs";
2
- import { NodeProcess } from "./node.mjs";
3
-
4
- //#region src/runtime/bun.d.ts
5
- /**
6
- * Create a runtime adapter backed by Bun's Node-compatible `process` global.
7
- *
8
- * Bun exposes `globalThis.process` with the same shape as Node.js, so this
9
- * delegates entirely to {@link createNodeAdapter}. If Bun-specific optimizations
10
- * are needed in the future (e.g. `Bun.write` for I/O), they can be layered
11
- * here without changing the public API.
12
- *
13
- * @param proc - Override the process object (useful for testing the adapter itself).
14
- * @returns A {@linkcode RuntimeAdapter} backed by Bun's process state.
15
- *
16
- * @example
17
- * ```ts
18
- * import { cli } from '@kjanat/dreamcli';
19
- * import { createBunAdapter } from '@kjanat/dreamcli/runtime';
20
- *
21
- * cli('mycli')
22
- * .command(deploy)
23
- * .run({ adapter: createBunAdapter() });
24
- * ```
25
- */
26
- declare function createBunAdapter(proc?: NodeProcess): RuntimeAdapter;
27
- //#endregion
28
- export { createBunAdapter };
@@ -1,28 +0,0 @@
1
- import { createNodeAdapter } from "./node.mjs";
2
- //#region src/runtime/bun.ts
3
- /**
4
- * Create a runtime adapter backed by Bun's Node-compatible `process` global.
5
- *
6
- * Bun exposes `globalThis.process` with the same shape as Node.js, so this
7
- * delegates entirely to {@link createNodeAdapter}. If Bun-specific optimizations
8
- * are needed in the future (e.g. `Bun.write` for I/O), they can be layered
9
- * here without changing the public API.
10
- *
11
- * @param proc - Override the process object (useful for testing the adapter itself).
12
- * @returns A {@linkcode RuntimeAdapter} backed by Bun's process state.
13
- *
14
- * @example
15
- * ```ts
16
- * import { cli } from '@kjanat/dreamcli';
17
- * import { createBunAdapter } from '@kjanat/dreamcli/runtime';
18
- *
19
- * cli('mycli')
20
- * .command(deploy)
21
- * .run({ adapter: createBunAdapter() });
22
- * ```
23
- */
24
- function createBunAdapter(proc) {
25
- return createNodeAdapter(proc);
26
- }
27
- //#endregion
28
- export { createBunAdapter };