@kjanat/dreamcli 2.5.0 → 3.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 (89) hide show
  1. package/CHANGELOG.md +128 -1
  2. package/README.md +9 -2
  3. package/dist/core/cli/index.d.mts +109 -16
  4. package/dist/core/cli/index.mjs +1 -1
  5. package/dist/core/cli/planner.d.mts +27 -5
  6. package/dist/core/cli/planner.mjs +1 -1
  7. package/dist/core/cli/root-help.d.mts +16 -2
  8. package/dist/core/cli/root-help.mjs +3 -5
  9. package/dist/core/cli/root-surface.d.mts +18 -3
  10. package/dist/core/cli/root-surface.mjs +1 -1
  11. package/dist/core/cli/runtime-preflight.d.mts +16 -1
  12. package/dist/core/cli/runtime-preflight.mjs +1 -1
  13. package/dist/core/completion/index.d.mts +32 -1
  14. package/dist/core/completion/index.mjs +1 -1
  15. package/dist/core/completion/shells/shared.d.mts +10 -0
  16. package/dist/core/completion/shells/shared.mjs +1 -1
  17. package/dist/core/help/index.d.mts +45 -1
  18. package/dist/core/help/index.mjs +6 -6
  19. package/dist/core/json-schema/index.mjs +1 -1
  20. package/dist/core/json-schema/meta-descriptions.generated.d.mts +38 -38
  21. package/dist/core/parse/index.d.mts +15 -1
  22. package/dist/core/parse/index.mjs +1 -1
  23. package/dist/core/prompt/index.d.mts +11 -3
  24. package/dist/core/prompt/index.mjs +3 -3
  25. package/dist/core/resolve/coerce.mjs +1 -1
  26. package/dist/core/resolve/flags.mjs +1 -1
  27. package/dist/core/resolve/property.d.mts +2 -0
  28. package/dist/core/resolve/property.mjs +1 -1
  29. package/dist/core/schema/arg.d.mts +90 -10
  30. package/dist/core/schema/arg.mjs +1 -1
  31. package/dist/core/schema/command.d.mts +3 -1
  32. package/dist/core/schema/flag.d.mts +92 -2
  33. package/dist/core/schema/flag.mjs +1 -1
  34. package/dist/core/schema/index.d.mts +2 -1
  35. package/dist/core/schema/number-constraints.d.mts +96 -0
  36. package/dist/core/schema/number-constraints.mjs +1 -0
  37. package/dist/core/schema/prompt.d.mts +15 -0
  38. package/dist/core/schema/run.d.mts +4 -4
  39. package/dist/core/testkit/index.d.mts +9 -5
  40. package/dist/core/testkit/index.mjs +1 -1
  41. package/dist/index.d.mts +2 -1
  42. package/dist/index.mjs +1 -1
  43. package/dist/runtime/auto.mjs +1 -1
  44. package/dist/runtime/bun.mjs +1 -1
  45. package/dist/runtime/deno.mjs +2 -2
  46. package/dist/runtime/node.mjs +2 -2
  47. package/dist/version.mjs +1 -1
  48. package/examples/basic.ts +5 -1
  49. package/examples/gh/package.json +2 -7
  50. package/examples/pwsh-demo/package.json +1 -7
  51. package/examples/pwsh-demo/src/main.test.ts +1 -4
  52. package/examples/pwsh-demo/src/main.ts +14 -4
  53. package/examples/transport-launcher.ts +85 -0
  54. package/package.json +15 -24
  55. package/src/core/cli/dispatch.ts +7 -1
  56. package/src/core/cli/index.ts +235 -34
  57. package/src/core/cli/planner.ts +192 -23
  58. package/src/core/cli/root-help.ts +195 -105
  59. package/src/core/cli/root-surface.ts +25 -12
  60. package/src/core/cli/runtime-preflight.ts +20 -2
  61. package/src/core/completion/index.ts +50 -0
  62. package/src/core/completion/shells/powershell.ts +2 -2
  63. package/src/core/completion/shells/shared.ts +30 -3
  64. package/src/core/execution/index.ts +1 -4
  65. package/src/core/help/index.ts +57 -10
  66. package/src/core/json-schema/index.ts +23 -4
  67. package/src/core/json-schema/meta-descriptions.generated.ts +115 -98
  68. package/src/core/parse/index.ts +62 -1
  69. package/src/core/prompt/index.ts +54 -14
  70. package/src/core/resolve/coerce.ts +73 -5
  71. package/src/core/resolve/flags.ts +14 -0
  72. package/src/core/resolve/property.ts +4 -4
  73. package/src/core/schema/arg.ts +125 -3
  74. package/src/core/schema/command.ts +3 -1
  75. package/src/core/schema/flag.ts +120 -4
  76. package/src/core/schema/index.ts +5 -0
  77. package/src/core/schema/number-constraints.ts +153 -0
  78. package/src/core/schema/prompt.ts +15 -0
  79. package/src/core/schema/run.ts +4 -4
  80. package/src/core/testkit/index.ts +32 -8
  81. package/src/index.ts +2 -0
  82. package/src/runtime/auto.ts +0 -24
  83. package/src/runtime/bun.ts +0 -7
  84. package/src/runtime/deno.ts +0 -2
  85. package/src/runtime/node.ts +0 -11
  86. package/src/runtime/support.ts +1 -59
  87. package/src/schema.ts +16 -0
  88. package/dist/runtime/support.d.mts +0 -42
  89. package/dist/runtime/support.mjs +0 -1
@@ -17,6 +17,7 @@
17
17
  import { buildRunResult, executeCommand } from '#internals/core/execution/index.ts';
18
18
  import type { CapturedOutput } from '#internals/core/output/index.ts';
19
19
  import { createCaptureOutput } from '#internals/core/output/index.ts';
20
+ import { includesBeforeSeparator, stripBeforeSeparator } from '#internals/core/parse/index.ts';
20
21
  import type { CommandMeta, Out, RunnableCommand } from '#internals/core/schema/command.ts';
21
22
  import type { RunOptions, RunResult } from '#internals/core/schema/run.ts';
22
23
 
@@ -30,16 +31,20 @@ import type { RunOptions, RunResult } from '#internals/core/schema/run.ts';
30
31
  * Run a command builder against the given argv with injected options.
31
32
  *
32
33
  * This is the testkit wrapper around the shared executor:
33
- * 1. Create or reuse capture output
34
- * 2. Build standalone schema/meta defaults when CLI dispatch did not
35
- * 3. Delegate parse -> resolve -> execute to the shared executor
36
- * 4. Return the structured result with captured buffers
34
+ * 1. Apply the CLI root-flag layer (detect/strip `--json`) so copied real argv works
35
+ * 2. Create or reuse capture output
36
+ * 3. Build standalone schema/meta defaults when CLI dispatch did not
37
+ * 4. Delegate parse -> resolve -> execute to the shared executor
38
+ * 5. Return the structured result with captured buffers
37
39
  *
38
40
  * Errors are normalized by the shared executor into structured {@linkcode RunResult}s
39
41
  * with appropriate exit codes. The function never throws.
40
42
  *
41
43
  * @param cmd - The command builder (must have an action handler)
42
- * @param argv - Raw argv strings (NOT including the command name itself)
44
+ * @param argv - Raw argv strings (NOT including the command name itself). A
45
+ * CLI-level `--json` before the `--` separator is honored and stripped here,
46
+ * just like the real CLI root — so `['--json']` enables JSON mode rather than
47
+ * failing as an unknown flag. Equivalent to passing `{ jsonMode: true }`.
43
48
  * @param options - Injectable runtime state
44
49
  * @returns Structured run result with exit code and captured output
45
50
  */
@@ -48,6 +53,16 @@ async function runCommand(
48
53
  argv: readonly string[],
49
54
  options?: RunOptions,
50
55
  ): Promise<RunResult> {
56
+ // Root-flag layer mirroring `CLIBuilder.execute()`: `--json` is owned by the
57
+ // CLI root, not the command schema, so it would otherwise reach `parse()` as
58
+ // an unknown flag (#33). Detect it before the `--` separator (a literal
59
+ // `--json` positional after `--` survives), enable JSON mode, and strip it so
60
+ // the command schema never sees it. The explicit `options.jsonMode` keeps
61
+ // working — either source enables JSON mode.
62
+ const hasJsonFlag = includesBeforeSeparator(argv, '--json');
63
+ const jsonMode = hasJsonFlag || options?.jsonMode === true;
64
+ const effectiveArgv = hasJsonFlag ? stripBeforeSeparator(argv, '--json') : argv;
65
+
51
66
  let out: Out;
52
67
  let captured: CapturedOutput;
53
68
  if (options?.out !== undefined) {
@@ -56,7 +71,7 @@ async function runCommand(
56
71
  } else {
57
72
  const captureOptions = {
58
73
  ...(options?.verbosity !== undefined ? { verbosity: options.verbosity } : {}),
59
- ...(options?.jsonMode !== undefined ? { jsonMode: options.jsonMode } : {}),
74
+ ...(jsonMode ? { jsonMode } : {}),
60
75
  ...(options?.isTTY !== undefined ? { isTTY: options.isTTY } : {}),
61
76
  };
62
77
  [out, captured] = createCaptureOutput(
@@ -74,13 +89,22 @@ async function runCommand(
74
89
  command: schema.name,
75
90
  };
76
91
 
92
+ // Thread the effective JSON mode into the executor so its error path renders
93
+ // structured JSON, matching dispatch where the planner sets `options.jsonMode`.
94
+ const effectiveOptions: RunOptions | undefined =
95
+ options !== undefined
96
+ ? { ...options, ...(jsonMode ? { jsonMode } : {}) }
97
+ : jsonMode
98
+ ? { jsonMode }
99
+ : undefined;
100
+
77
101
  const result = await executeCommand({
78
102
  command: cmd,
79
- argv,
103
+ argv: effectiveArgv,
80
104
  out,
81
105
  schema,
82
106
  meta,
83
- ...(options !== undefined ? { options } : {}),
107
+ ...(effectiveOptions !== undefined ? { options: effectiveOptions } : {}),
84
108
  });
85
109
 
86
110
  return buildRunResult(result, captured);
package/src/index.ts CHANGED
@@ -143,6 +143,8 @@ export type {
143
143
  MiddlewareHandler,
144
144
  MiddlewareParams,
145
145
  MultiselectPromptConfig,
146
+ NumberConstraints,
147
+ NumberConstraintViolation,
146
148
  Out,
147
149
  ProgressHandle,
148
150
  ProgressOptions,
@@ -16,27 +16,6 @@ import { createDenoAdapter } from './deno.ts';
16
16
  import type { GlobalForDetect } from './detect.ts';
17
17
  import { detectRuntime } from './detect.ts';
18
18
  import { createNodeAdapter } from './node.ts';
19
- import { assertRuntimeVersionSupported } from './support.ts';
20
-
21
- function detectRuntimeVersion(
22
- runtime: ReturnType<typeof detectRuntime>,
23
- globals: GlobalForDetect,
24
- ): string | undefined {
25
- switch (runtime) {
26
- case 'bun':
27
- return globals.Bun?.version;
28
- case 'deno':
29
- return globals.Deno?.version?.deno;
30
- case 'node':
31
- return globals.process?.versions?.node;
32
- case 'unknown':
33
- return undefined;
34
- default: {
35
- const _exhaustive: never = runtime;
36
- return _exhaustive;
37
- }
38
- }
39
- }
40
19
 
41
20
  function isDenoNamespace(value: unknown): value is DenoNamespace {
42
21
  if (typeof value !== 'object' || value === null) return false;
@@ -86,9 +65,6 @@ function getInjectedDenoNamespace(globals: GlobalForDetect): DenoNamespace | und
86
65
  function createAdapter(globals?: GlobalForDetect): RuntimeAdapter {
87
66
  const runtimeGlobals = globals ?? globalThis;
88
67
  const runtime = detectRuntime(runtimeGlobals);
89
- if (runtime !== 'unknown') {
90
- assertRuntimeVersionSupported(runtime, detectRuntimeVersion(runtime, runtimeGlobals));
91
- }
92
68
 
93
69
  switch (runtime) {
94
70
  case 'bun':
@@ -15,12 +15,6 @@
15
15
  import type { RuntimeAdapter } from './adapter.ts';
16
16
  import type { NodeProcess } from './node.ts';
17
17
  import { createNodeAdapter } from './node.ts';
18
- import { assertRuntimeVersionSupported } from './support.ts';
19
-
20
- function resolveBunVersion(proc?: NodeProcess): string | undefined {
21
- if (proc?.versions?.bun !== undefined) return proc.versions.bun;
22
- return (globalThis as unknown as { Bun?: { version?: string } }).Bun?.version;
23
- }
24
18
 
25
19
  // --- Bun adapter factory
26
20
 
@@ -46,7 +40,6 @@ function resolveBunVersion(proc?: NodeProcess): string | undefined {
46
40
  * ```
47
41
  */
48
42
  function createBunAdapter(proc?: NodeProcess): RuntimeAdapter {
49
- assertRuntimeVersionSupported('bun', resolveBunVersion(proc));
50
43
  return createNodeAdapter(proc);
51
44
  }
52
45
 
@@ -23,7 +23,6 @@ import type { WriteFn } from '#internals/core/output/index.ts';
23
23
  import type { ReadFn } from '#internals/core/prompt/index.ts';
24
24
  import type { RuntimeAdapter } from './adapter.ts';
25
25
  import { resolveConfigDirectory, resolveHomeDirectory } from './paths.ts';
26
- import { assertRuntimeVersionSupported } from './support.ts';
27
26
 
28
27
  // --- Minimal Deno namespace shape — avoids @types/deno dependency
29
28
 
@@ -169,7 +168,6 @@ function safeCwd(deno: DenoNamespace): string {
169
168
  */
170
169
  function createDenoAdapter(ns?: DenoNamespace): RuntimeAdapter {
171
170
  const d = ns ?? getDenoNamespace();
172
- assertRuntimeVersionSupported('deno', d.version?.deno);
173
171
  const encoder = new TextEncoder();
174
172
 
175
173
  // --- Synthetic argv: Deno.args has user args only (no binary/script) ---
@@ -16,7 +16,6 @@ import type { WriteFn } from '#internals/core/output/index.ts';
16
16
  import type { ReadFn } from '#internals/core/prompt/index.ts';
17
17
  import type { RuntimeAdapter } from './adapter.ts';
18
18
  import { resolveConfigDirectory, resolveHomeDirectory } from './paths.ts';
19
- import { assertRuntimeVersionSupported } from './support.ts';
20
19
 
21
20
  // --- Node.js error shape — for ENOENT detection without @types/node
22
21
 
@@ -142,15 +141,6 @@ function resolveConfigDir(
142
141
  return resolveConfigDirectory(env, platform === 'win32', homedir);
143
142
  }
144
143
 
145
- function assertProcessRuntimeSupported(proc: NodeProcess): void {
146
- if (proc.versions?.bun !== undefined) {
147
- assertRuntimeVersionSupported('bun', proc.versions.bun);
148
- return;
149
- }
150
-
151
- assertRuntimeVersionSupported('node', proc.versions?.node);
152
- }
153
-
154
144
  // --- Node adapter factory
155
145
 
156
146
  /**
@@ -176,7 +166,6 @@ function assertProcessRuntimeSupported(proc: NodeProcess): void {
176
166
  */
177
167
  function createNodeAdapter(proc?: NodeProcess): RuntimeAdapter {
178
168
  const p = proc ?? getNodeProcess();
179
- assertProcessRuntimeSupported(p);
180
169
 
181
170
  const stdoutWrite: WriteFn = (data) => {
182
171
  p.stdout.write(data);
@@ -58,14 +58,6 @@ const SUPPORTED_RUNTIMES: readonly RuntimeSupportEntry[] = [
58
58
  },
59
59
  ];
60
60
 
61
- interface ParsedVersion {
62
- readonly major: number;
63
- readonly minor: number;
64
- readonly patch: number;
65
- }
66
-
67
- const VERSION_PATTERN = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?/;
68
-
69
61
  /** Look up the support entry for a given runtime. Throws on unknown runtime. @internal */
70
62
  function getRuntimeSupport(runtime: SupportedRuntime): RuntimeSupportEntry {
71
63
  for (const entry of SUPPORTED_RUNTIMES) {
@@ -75,61 +67,11 @@ function getRuntimeSupport(runtime: SupportedRuntime): RuntimeSupportEntry {
75
67
  throw new Error(`Unknown supported runtime '${runtime}'`);
76
68
  }
77
69
 
78
- function parseVersion(version: string): ParsedVersion | undefined {
79
- const match = VERSION_PATTERN.exec(version);
80
- if (match === null) return undefined;
81
-
82
- const major = Number.parseInt(match[1] ?? '', 10);
83
- const minorText = match[2];
84
- const minor = minorText === undefined ? 0 : Number.parseInt(minorText, 10);
85
- const patchText = match[3];
86
- const patch = patchText === undefined ? 0 : Number.parseInt(patchText, 10);
87
-
88
- if (Number.isNaN(major) || Number.isNaN(minor) || Number.isNaN(patch)) {
89
- return undefined;
90
- }
91
-
92
- return { major, minor, patch };
93
- }
94
-
95
- function compareVersions(left: ParsedVersion, right: ParsedVersion): number {
96
- if (left.major !== right.major) return left.major - right.major;
97
- if (left.minor !== right.minor) return left.minor - right.minor;
98
- return left.patch - right.patch;
99
- }
100
-
101
70
  /** Format a human-readable version requirement string (e.g. `'Node.js >= 22.22.2'`). @internal */
102
71
  function formatRuntimeRequirement(runtime: SupportedRuntime): string {
103
72
  const support = getRuntimeSupport(runtime);
104
73
  return `${support.displayName} >= ${support.minimum}`;
105
74
  }
106
75
 
107
- /** Check whether a version string meets the minimum for the given runtime. @internal */
108
- function isRuntimeVersionSupported(runtime: SupportedRuntime, version: string): boolean {
109
- const parsedVersion = parseVersion(version);
110
- const minimumVersion = parseVersion(getRuntimeSupport(runtime).minimum);
111
- if (parsedVersion === undefined || minimumVersion === undefined) return false;
112
- return compareVersions(parsedVersion, minimumVersion) >= 0;
113
- }
114
-
115
- /** Throw if the detected version is below the minimum. No-op when version is undefined. @internal */
116
- function assertRuntimeVersionSupported(
117
- runtime: SupportedRuntime,
118
- version: string | undefined,
119
- ): void {
120
- if (version === undefined) return;
121
- if (isRuntimeVersionSupported(runtime, version)) return;
122
-
123
- throw new Error(
124
- `@kjanat/dreamcli requires ${formatRuntimeRequirement(runtime)}. Detected ${getRuntimeSupport(runtime).displayName} ${version}.`,
125
- );
126
- }
127
-
128
76
  export type { RuntimeSupportEntry, SupportedRuntime };
129
- export {
130
- assertRuntimeVersionSupported,
131
- formatRuntimeRequirement,
132
- getRuntimeSupport,
133
- isRuntimeVersionSupported,
134
- SUPPORTED_RUNTIMES,
135
- };
77
+ export { formatRuntimeRequirement, getRuntimeSupport, SUPPORTED_RUNTIMES };
package/src/schema.ts ADDED
@@ -0,0 +1,16 @@
1
+ /**
2
+ * JSON Schema for DreamCLI definition files.
3
+ *
4
+ * Re-exports the generated `dreamcli.schema.json` meta-schema so tooling,
5
+ * editors, and validation libraries can import it as a typed module.
6
+ *
7
+ * @example
8
+ * ```ts
9
+ * import schema from '@kjanat/dreamcli/schema';
10
+ *
11
+ * console.log(schema.$id); // "dreamcli.schema.json"
12
+ * ```
13
+ *
14
+ * @module @kjanat/dreamcli/schema
15
+ */
16
+ export { default } from '../dreamcli.schema.json' with { type: 'json' };
@@ -1,42 +0,0 @@
1
- //#region src/runtime/support.d.ts
2
- /**
3
- * Runtime compatibility matrix and version guard helpers.
4
- *
5
- * Keeps the supported runtime story in one place so adapter guards,
6
- * package engines, and docs can stay aligned.
7
- *
8
- * @internal
9
- * @module @kjanat/dreamcli/runtime/support
10
- */
11
- type SupportedRuntime = 'node' | 'bun' | 'deno';
12
- /**
13
- * Support entry for a single runtime: version bounds, display names, and adapter mapping.
14
- *
15
- * @internal
16
- */
17
- interface RuntimeSupportEntry {
18
- /** Runtime identifier key. */
19
- readonly runtime: SupportedRuntime;
20
- /** Human-readable name (e.g. `'Node.js'`, `'Bun'`). */
21
- readonly displayName: string;
22
- /** Minimum supported version (semver, e.g. `'22.22.2'`). */
23
- readonly minimum: string;
24
- /** `engines` range string for package.json (e.g. `'>=22.22.2'`). */
25
- readonly engineRange: string;
26
- /** npm/JSR package name that ships this adapter. */
27
- readonly packageName: string;
28
- /** Adapter factory function name (e.g. `'NodeAdapter'`). */
29
- readonly adapterName: string;
30
- }
31
- /** All supported runtimes with their version bounds and adapter metadata. @internal */
32
- declare const SUPPORTED_RUNTIMES: readonly RuntimeSupportEntry[];
33
- /** Look up the support entry for a given runtime. Throws on unknown runtime. @internal */
34
- declare function getRuntimeSupport(runtime: SupportedRuntime): RuntimeSupportEntry;
35
- /** Format a human-readable version requirement string (e.g. `'Node.js >= 22.22.2'`). @internal */
36
- declare function formatRuntimeRequirement(runtime: SupportedRuntime): string;
37
- /** Check whether a version string meets the minimum for the given runtime. @internal */
38
- declare function isRuntimeVersionSupported(runtime: SupportedRuntime, version: string): boolean;
39
- /** Throw if the detected version is below the minimum. No-op when version is undefined. @internal */
40
- declare function assertRuntimeVersionSupported(runtime: SupportedRuntime, version: string | undefined): void;
41
- //#endregion
42
- export { type RuntimeSupportEntry, SUPPORTED_RUNTIMES, type SupportedRuntime, assertRuntimeVersionSupported, formatRuntimeRequirement, getRuntimeSupport, isRuntimeVersionSupported };
@@ -1 +0,0 @@
1
- const e=[{runtime:`node`,displayName:`Node.js`,minimum:`22.22.2`,engineRange:`>=22.22.2`,packageName:`@kjanat/dreamcli`,adapterName:`NodeAdapter`},{runtime:`bun`,displayName:`Bun`,minimum:`1.3`,engineRange:`>=1.3`,packageName:`@kjanat/dreamcli`,adapterName:`BunAdapter`},{runtime:`deno`,displayName:`Deno`,minimum:`2.6.0`,engineRange:`>=2.6.0`,packageName:`@kjanat/dreamcli`,adapterName:`DenoAdapter`}],t=/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/;function n(t){for(let n of e)if(n.runtime===t)return n;throw Error(`Unknown supported runtime '${t}'`)}function r(e){let n=t.exec(e);if(n===null)return;let r=Number.parseInt(n[1]??``,10),i=n[2],a=i===void 0?0:Number.parseInt(i,10),o=n[3],s=o===void 0?0:Number.parseInt(o,10);if(!(Number.isNaN(r)||Number.isNaN(a)||Number.isNaN(s)))return{major:r,minor:a,patch:s}}function i(e,t){return e.major===t.major?e.minor===t.minor?e.patch-t.patch:e.minor-t.minor:e.major-t.major}function a(e){let t=n(e);return`${t.displayName} >= ${t.minimum}`}function o(e,t){let a=r(t),o=r(n(e).minimum);return a===void 0||o===void 0?!1:i(a,o)>=0}function s(e,t){if(t!==void 0&&!o(e,t))throw Error(`@kjanat/dreamcli requires ${a(e)}. Detected ${n(e).displayName} ${t}.`)}export{s as assertRuntimeVersionSupported};