@kjanat/dreamcli 3.0.0-rc.4 → 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,37 @@ 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
+
10
41
  ## [3.0.0-rc.4] - 2026-07-06
11
42
 
12
43
  ### Added
@@ -1052,7 +1083,9 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
1052
1083
  - MIT License.
1053
1084
  - Markdownlint configuration.
1054
1085
 
1055
- [Unreleased]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.4...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
1056
1089
  [3.0.0-rc.4]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.3...v3.0.0-rc.4
1057
1090
  [3.0.0-rc.3]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.2...v3.0.0-rc.3
1058
1091
  [3.0.0-rc.2]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.1...v3.0.0-rc.2
@@ -684,9 +684,16 @@ var CLIBuilder = class CLIBuilder {
684
684
  return adapter.exit(preflight.error.exitCode);
685
685
  }
686
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;
687
693
  const executeOptions = {
688
694
  ...options,
689
695
  ...preflight.inputs,
696
+ ...runtimeHelpOptions !== void 0 ? { help: runtimeHelpOptions } : {},
690
697
  out: createOutput({
691
698
  stdout: adapter.stdout,
692
699
  stderr: adapter.stderr,
@@ -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.4";
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 = "7314c6f";
5
+ const DREAMCLI_REVISION = "c63883e";
6
6
  //#endregion
7
7
  export { DREAMCLI_REVISION, DREAMCLI_VERSION };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kjanat/dreamcli",
3
- "version": "3.0.0-rc.4",
3
+ "version": "3.0.0-rc.6",
4
4
  "description": "Schema-first, fully typed TypeScript CLI framework",
5
5
  "keywords": [
6
6
  "dreamcli",
@@ -159,8 +159,7 @@
159
159
  "npm": "11.18.0"
160
160
  },
161
161
  "publishConfig": {
162
- "access": "public",
163
- "provenance": true
162
+ "access": "public"
164
163
  },
165
164
  "catalog": {
166
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 };