@kjanat/dreamcli 2.5.0 → 3.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 (160) hide show
  1. package/CHANGELOG.md +153 -1
  2. package/README.md +9 -2
  3. package/dist/core/cli/dispatch.mjs +214 -1
  4. package/dist/core/cli/help-links.mjs +41 -1
  5. package/dist/core/cli/index.d.mts +109 -16
  6. package/dist/core/cli/index.mjs +901 -1
  7. package/dist/core/cli/planner.d.mts +27 -5
  8. package/dist/core/cli/planner.mjs +300 -1
  9. package/dist/core/cli/plugin.mjs +41 -1
  10. package/dist/core/cli/propagate.mjs +57 -1
  11. package/dist/core/cli/root-help.d.mts +16 -2
  12. package/dist/core/cli/root-help.mjs +208 -6
  13. package/dist/core/cli/root-surface.d.mts +18 -3
  14. package/dist/core/cli/root-surface.mjs +27 -1
  15. package/dist/core/cli/runtime-preflight.d.mts +16 -1
  16. package/dist/core/cli/runtime-preflight.mjs +168 -1
  17. package/dist/core/completion/index.d.mts +32 -1
  18. package/dist/core/completion/index.mjs +90 -1
  19. package/dist/core/completion/shells/bash.mjs +304 -3
  20. package/dist/core/completion/shells/fish.mjs +159 -2
  21. package/dist/core/completion/shells/powershell.mjs +353 -2
  22. package/dist/core/completion/shells/shared.d.mts +10 -0
  23. package/dist/core/completion/shells/shared.mjs +154 -1
  24. package/dist/core/completion/shells/zsh.mjs +244 -2
  25. package/dist/core/config/index.mjs +246 -1
  26. package/dist/core/config/package-json.mjs +385 -3
  27. package/dist/core/errors/index.mjs +87 -1
  28. package/dist/core/execution/index.mjs +189 -1
  29. package/dist/core/help/ansi.mjs +122 -2
  30. package/dist/core/help/index.d.mts +45 -1
  31. package/dist/core/help/index.mjs +329 -7
  32. package/dist/core/json-schema/index.mjs +487 -9
  33. package/dist/core/json-schema/meta-descriptions.generated.d.mts +38 -38
  34. package/dist/core/json-schema/meta-descriptions.generated.mjs +93 -28
  35. package/dist/core/output/activity.mjs +452 -1
  36. package/dist/core/output/bind.mjs +56 -1
  37. package/dist/core/output/contracts.mjs +57 -1
  38. package/dist/core/output/display-value.mjs +32 -1
  39. package/dist/core/output/index.d.mts +21 -0
  40. package/dist/core/output/index.mjs +442 -2
  41. package/dist/core/output/renderers.mjs +46 -1
  42. package/dist/core/output/writer.mjs +12 -1
  43. package/dist/core/parse/index.d.mts +15 -1
  44. package/dist/core/parse/index.mjs +555 -1
  45. package/dist/core/prompt/index.d.mts +11 -4
  46. package/dist/core/prompt/index.mjs +348 -6
  47. package/dist/core/resolve/args.mjs +105 -1
  48. package/dist/core/resolve/coerce.mjs +279 -1
  49. package/dist/core/resolve/config.mjs +19 -1
  50. package/dist/core/resolve/errors.mjs +140 -2
  51. package/dist/core/resolve/flags.mjs +196 -1
  52. package/dist/core/resolve/index.mjs +85 -1
  53. package/dist/core/resolve/property.d.mts +2 -1
  54. package/dist/core/resolve/property.mjs +45 -1
  55. package/dist/core/schema/arg.d.mts +90 -10
  56. package/dist/core/schema/arg.mjs +463 -1
  57. package/dist/core/schema/command.d.mts +21 -1
  58. package/dist/core/schema/command.mjs +712 -1
  59. package/dist/core/schema/flag.d.mts +92 -2
  60. package/dist/core/schema/flag.mjs +453 -1
  61. package/dist/core/schema/index.d.mts +2 -1
  62. package/dist/core/schema/middleware.mjs +41 -1
  63. package/dist/core/schema/number-constraints.d.mts +96 -0
  64. package/dist/core/schema/number-constraints.mjs +60 -0
  65. package/dist/core/schema/prompt.d.mts +15 -0
  66. package/dist/core/schema/run.d.mts +4 -4
  67. package/dist/core/schema-dsl/runtime.mjs +271 -2
  68. package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
  69. package/dist/core/testkit/index.d.mts +9 -5
  70. package/dist/core/testkit/index.mjs +83 -1
  71. package/dist/index.d.mts +3 -1
  72. package/dist/index.mjs +22 -1
  73. package/dist/runtime/adapter.mjs +82 -1
  74. package/dist/runtime/auto.mjs +46 -1
  75. package/dist/runtime/bun.mjs +28 -1
  76. package/dist/runtime/deno.mjs +217 -2
  77. package/dist/runtime/detect.mjs +45 -1
  78. package/dist/runtime/node.mjs +169 -2
  79. package/dist/runtime/paths.mjs +48 -1
  80. package/dist/runtime.mjs +7 -1
  81. package/dist/strings.mjs +22 -1
  82. package/dist/testkit.mjs +5 -1
  83. package/dist/version.mjs +7 -1
  84. package/examples/basic.ts +5 -1
  85. package/examples/gh/package.json +2 -7
  86. package/examples/pwsh-demo/package.json +1 -7
  87. package/examples/pwsh-demo/src/main.test.ts +1 -4
  88. package/examples/pwsh-demo/src/main.ts +14 -4
  89. package/examples/transport-launcher.ts +85 -0
  90. package/package.json +23 -41
  91. package/dist/runtime/support.d.mts +0 -42
  92. package/dist/runtime/support.mjs +0 -1
  93. package/src/core/cli/dispatch.ts +0 -349
  94. package/src/core/cli/help-links.ts +0 -82
  95. package/src/core/cli/index.ts +0 -1413
  96. package/src/core/cli/planner.ts +0 -487
  97. package/src/core/cli/plugin.ts +0 -117
  98. package/src/core/cli/propagate.ts +0 -97
  99. package/src/core/cli/root-help.ts +0 -252
  100. package/src/core/cli/root-surface.ts +0 -74
  101. package/src/core/cli/runtime-preflight.ts +0 -438
  102. package/src/core/completion/index.ts +0 -88
  103. package/src/core/completion/shells/bash.ts +0 -459
  104. package/src/core/completion/shells/fish.ts +0 -259
  105. package/src/core/completion/shells/powershell.ts +0 -439
  106. package/src/core/completion/shells/shared.ts +0 -283
  107. package/src/core/completion/shells/zsh.ts +0 -381
  108. package/src/core/config/index.ts +0 -417
  109. package/src/core/config/package-json.ts +0 -560
  110. package/src/core/errors/index.ts +0 -193
  111. package/src/core/execution/index.ts +0 -268
  112. package/src/core/help/ansi.ts +0 -144
  113. package/src/core/help/index.ts +0 -516
  114. package/src/core/json-schema/index.ts +0 -891
  115. package/src/core/json-schema/meta-descriptions.generated.ts +0 -185
  116. package/src/core/output/activity.ts +0 -575
  117. package/src/core/output/bind.ts +0 -59
  118. package/src/core/output/contracts.ts +0 -194
  119. package/src/core/output/display-value.ts +0 -48
  120. package/src/core/output/index.ts +0 -704
  121. package/src/core/output/renderers.ts +0 -125
  122. package/src/core/output/writer.ts +0 -46
  123. package/src/core/parse/index.ts +0 -681
  124. package/src/core/prompt/index.ts +0 -583
  125. package/src/core/resolve/args.ts +0 -144
  126. package/src/core/resolve/coerce.ts +0 -432
  127. package/src/core/resolve/config.ts +0 -26
  128. package/src/core/resolve/contracts.ts +0 -135
  129. package/src/core/resolve/errors.ts +0 -227
  130. package/src/core/resolve/flags.ts +0 -255
  131. package/src/core/resolve/index.ts +0 -108
  132. package/src/core/resolve/property.ts +0 -99
  133. package/src/core/schema/activity.ts +0 -240
  134. package/src/core/schema/arg.ts +0 -719
  135. package/src/core/schema/command.ts +0 -1498
  136. package/src/core/schema/flag.ts +0 -801
  137. package/src/core/schema/index.ts +0 -91
  138. package/src/core/schema/middleware.ts +0 -171
  139. package/src/core/schema/prompt.ts +0 -156
  140. package/src/core/schema/run.ts +0 -198
  141. package/src/core/schema-dsl/index.ts +0 -109
  142. package/src/core/schema-dsl/parse.ts +0 -262
  143. package/src/core/schema-dsl/runtime.ts +0 -609
  144. package/src/core/schema-dsl/to-json-schema.ts +0 -102
  145. package/src/core/testkit/index.ts +0 -123
  146. package/src/index.ts +0 -179
  147. package/src/runtime/adapter.ts +0 -303
  148. package/src/runtime/auto.ts +0 -110
  149. package/src/runtime/bun.ts +0 -55
  150. package/src/runtime/deno.ts +0 -369
  151. package/src/runtime/detect.ts +0 -105
  152. package/src/runtime/index.ts +0 -21
  153. package/src/runtime/node-builtins.d.ts +0 -27
  154. package/src/runtime/node.ts +0 -300
  155. package/src/runtime/paths.ts +0 -64
  156. package/src/runtime/support.ts +0 -135
  157. package/src/runtime.ts +0 -31
  158. package/src/strings.ts +0 -34
  159. package/src/testkit.ts +0 -25
  160. package/src/version.ts +0 -20
@@ -1,11 +1,480 @@
1
- import{getFlagAliasNames as e}from"../schema/flag.mjs";import{parseSchema as t}from"../schema-dsl/runtime.mjs";import{nodeToJsonSchema as n}from"../schema-dsl/to-json-schema.mjs";import{definitionMetaSchemaDescriptions as r}from"./meta-descriptions.generated.mjs";function i(e){return{includeHidden:e?.includeHidden??!0,includePrompts:e?.includePrompts??!0}}const a=`https://cdn.jsdelivr.net/npm/@kjanat/dreamcli/dreamcli.schema.json`,o=`https://json-schema.org/draft/2020-12/schema`;function s(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function c(e,t){let n=i(t),r={$schema:a,name:e.name};return e.version!==void 0&&(r.version=e.version),e.description!==void 0&&(r.description=e.description),e.defaultCommand!==void 0&&(n.includeHidden||!e.defaultCommand.schema.hidden)&&(r.defaultCommand=e.defaultCommand.schema.name),r.commands=e.commands.filter(e=>n.includeHidden||!e.schema.hidden).map(e=>l(e.schema,n)),r}function l(e,t){let n={name:e.name};e.description!==void 0&&(n.description=e.description),e.aliases.length>0&&(n.aliases=[...e.aliases]),e.hidden&&(n.hidden=!0),e.examples.length>0&&(n.examples=e.examples.map(m));let r={};for(let[n,i]of Object.entries(e.flags))r[n]=u(i,t);return n.flags=r,n.args=e.args.map(d),n.commands=e.commands.filter(e=>t.includeHidden||!e.hidden).map(e=>l(e,t)),n}function u(t,n){let r={kind:t.kind,presence:t.presence};t.presence===`defaulted`&&w(t.defaultValue)&&(r.defaultValue=t.defaultValue);let i=e(t);return i.length>0&&(r.aliases=[...i]),t.envVar!==void 0&&(r.envVar=t.envVar),t.configPath!==void 0&&(r.configPath=t.configPath),t.description!==void 0&&(r.description=t.description),t.enumValues!==void 0&&(r.enumValues=[...t.enumValues]),t.elementSchema!==void 0&&(r.elementSchema=u(t.elementSchema,n)),n.includePrompts&&t.prompt!==void 0&&(r.prompt=f(t.prompt)),t.deprecated!==void 0&&(r.deprecated=t.deprecated),t.propagate&&(r.propagate=!0),r}function d(e){let{name:t,schema:n}=e,r={name:t,kind:n.kind,presence:n.presence};return n.variadic&&(r.variadic=!0),n.stdinMode&&(r.stdinMode=!0),n.presence===`defaulted`&&w(n.defaultValue)&&(r.defaultValue=n.defaultValue),n.description!==void 0&&(r.description=n.description),n.envVar!==void 0&&(r.envVar=n.envVar),n.enumValues!==void 0&&(r.enumValues=[...n.enumValues]),n.deprecated!==void 0&&(r.deprecated=n.deprecated),r}function f(e){let t={kind:e.kind,message:e.message};switch(e.kind){case`input`:e.placeholder!==void 0&&(t.placeholder=e.placeholder);break;case`select`:e.choices!==void 0&&(t.choices=e.choices.map(p));break;case`multiselect`:e.choices!==void 0&&(t.choices=e.choices.map(p)),e.min!==void 0&&(t.min=e.min),e.max!==void 0&&(t.max=e.max);break;case`confirm`:break}return t}function p(e){let t={value:e.value};return e.label!==void 0&&(t.label=e.label),e.description!==void 0&&(t.description=e.description),t}function m(e){let t={command:e.command};return e.description!==void 0&&(t.description=e.description),t}function h(e,t){let n=i(t);if(g(e))return{$schema:o,...v(e)};let r=[];for(let t of e.commands)!n.includeHidden&&t.schema.hidden||_(t.schema,``,r,n);if(r.length===1)return{$schema:o,...y(r[0]??{})};if(r.length>0){let t=e.defaultCommand!==void 0&&(n.includeHidden||!e.defaultCommand.schema.hidden)?e.defaultCommand.schema.name:void 0;return{$schema:o,oneOf:t===void 0?r:r.map(e=>b(e)===t?y(e):e)}}return{$schema:o,type:`object`}}function g(e){return`flags`in e&&`args`in e&&`middleware`in e&&`hasAction`in e}function _(e,t,n,r){let i=t?`${t}.${e.name}`:e.name;e.hasAction&&n.push(v(e,i));for(let t of e.commands)!r.includeHidden&&t.hidden||_(t,i,n,r)}function v(e,t){let n={},r=[];t!==void 0&&(n.command={const:t},r.push(`command`));for(let[t,i]of Object.entries(e.flags))n[t]=x(i),i.presence===`required`&&r.push(t);for(let t of e.args)n[t.name]=S(t.schema),t.schema.presence===`required`&&r.push(t.name);let i={type:`object`,properties:n,additionalProperties:!1};return r.length>0&&(i.required=r),i}function y(e){let t=e.properties,n=e.required,r=s(t)?{...t}:void 0,i=Array.isArray(n)?n.filter(e=>typeof e==`string`):void 0;r!==void 0&&delete r.command;let a=i?.filter(e=>e!==`command`),o={...e};return r!==void 0&&(o.properties=r),a!==void 0&&a.length>0?o.required=a:delete o.required,o}function b(e){let t=e.properties;if(!s(t))return;let n=t.command;return s(n)&&typeof n.const==`string`?n.const:void 0}function x(e){let t={};switch(e.kind){case`string`:t.type=`string`;break;case`number`:t.type=`number`;break;case`boolean`:t.type=`boolean`;break;case`enum`:t.type=`string`,e.enumValues!==void 0&&(t.enum=[...e.enumValues]);break;case`array`:t.type=`array`,e.elementSchema!==void 0&&(t.items=x(e.elementSchema));break;case`custom`:break}return e.description!==void 0&&(t.description=e.description),e.presence===`defaulted`&&w(e.defaultValue)&&(t.default=e.defaultValue),e.deprecated!==void 0&&(t.deprecated=e.deprecated),t}function S(e){let t=C(e),n=e.variadic?{type:`array`,items:t}:{...t};return e.description!==void 0&&(n.description=e.description),e.presence===`defaulted`&&w(e.defaultValue)&&(n.default=e.defaultValue),e.deprecated!==void 0&&(n.deprecated=e.deprecated),n}function C(e){switch(e.kind){case`string`:return{type:`string`};case`number`:return{type:`number`};case`enum`:{let t={type:`string`};return e.enumValues!==void 0&&(t.enum=[...e.enumValues]),t}case`custom`:return{}}}function w(e,t=new WeakSet){if(e===void 0)return!1;if(e===null)return!0;let n=typeof e;if(n===`string`||n===`boolean`)return!0;if(n===`number`)return Number.isFinite(e);if(n===`function`||n===`symbol`||n===`bigint`)return!1;if(Array.isArray(e)){if(t.has(e))return!1;t.add(e);try{return e.every(e=>w(e,t))}finally{t.delete(e)}}if(n===`object`){let n=e;if(!T(n)||t.has(n))return!1;t.add(n);try{return Object.values(n).every(e=>w(e,t))}finally{t.delete(n)}}return!1}function T(e){let t=Object.getPrototypeOf(e);return t===Object.prototype||t===null}function E(e){return n(t(e))}function D(e,t){let n=e.properties,r=typeof n==`object`&&n&&T(n)&&t.properties!==void 0?Object.fromEntries(Object.entries(n).map(([e,n])=>{let r=t.properties?.[e];return r===void 0||typeof n!=`object`||!n||!T(n)?[e,n]:[e,D(n,r)]})):void 0;return{...e,...t.description===void 0?{}:{description:t.description},...r===void 0?{}:{properties:r}}}function O(e,t){let n=D(e,t.root),r=n.$defs;return typeof r!=`object`||!r||!T(r)?n:{...n,$defs:Object.fromEntries(Object.entries(r).map(([e,n])=>{let r=t.defs[e];return r===void 0||typeof n!=`object`||!n||!T(n)?[e,n]:[e,D(n,r)]}))}}const k=O({$schema:o,$id:a,title:`@kjanat/dreamcli definition schema`,description:`Describes the structure of a CLI built with dreamcli — commands, flags, args, types, constraints, env bindings, and prompts.`,...E(`{
2
- $schema: '${a}';
1
+ import { getFlagAliasNames } from "../schema/flag.mjs";
2
+ import { parseSchema } from "../schema-dsl/runtime.mjs";
3
+ import { nodeToJsonSchema } from "../schema-dsl/to-json-schema.mjs";
4
+ import { definitionMetaSchemaDescriptions } from "./meta-descriptions.generated.mjs";
5
+ //#region src/core/json-schema/index.ts
6
+ /**
7
+ * Apply defaults to optional {@link JsonSchemaOptions}.
8
+ *
9
+ * @param options - User-supplied schema generation options, or `undefined` for all defaults.
10
+ * @returns Fully resolved options with defaults applied.
11
+ */
12
+ function resolveOptions(options) {
13
+ return {
14
+ includeHidden: options?.includeHidden ?? true,
15
+ includePrompts: options?.includePrompts ?? true
16
+ };
17
+ }
18
+ /**
19
+ * `$schema` URL for definition documents.
20
+ *
21
+ * Resolves via the actual file path on the CDN (`dreamcli.schema.json`).
22
+ * For offline or local-first workflows, use
23
+ * `./node_modules/@kjanat/dreamcli/dreamcli.schema.json`.
24
+ */
25
+ const DEFINITION_SCHEMA_URL = "https://cdn.jsdelivr.net/npm/@kjanat/dreamcli/dreamcli.schema.json";
26
+ /** Meta-schema URL for JSON Schema draft 2020-12 (input validation). */
27
+ const JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
28
+ function isRecord(value) {
29
+ return typeof value === "object" && value !== null && !Array.isArray(value);
30
+ }
31
+ /**
32
+ * Generate a definition metadata document describing the CLI's structure.
33
+ *
34
+ * Walks the full command tree and produces a plain JSON-serializable object
35
+ * representing all commands, subcommands, flags, args, and metadata.
36
+ * Non-serializable runtime values (parse functions, middleware handlers,
37
+ * interactive resolvers) are omitted.
38
+ *
39
+ * @param schema - The CLI schema from `CLIBuilder.schema`.
40
+ * @param options - Generation options.
41
+ * @returns A plain object suitable for `JSON.stringify()`.
42
+ *
43
+ * @example
44
+ * ```ts
45
+ * const app = cli('myapp').version('1.0.0').command(deploy);
46
+ * const definition = generateSchema(app.schema);
47
+ * writeFileSync('cli-schema.json', JSON.stringify(definition, null, 2));
48
+ * ```
49
+ */
50
+ function generateSchema(schema, options) {
51
+ const opts = resolveOptions(options);
52
+ const result = {
53
+ $schema: DEFINITION_SCHEMA_URL,
54
+ name: schema.name
55
+ };
56
+ if (schema.version !== void 0) result.version = schema.version;
57
+ if (schema.description !== void 0) result.description = schema.description;
58
+ if (schema.defaultCommand !== void 0 && (opts.includeHidden || !schema.defaultCommand.schema.hidden)) result.defaultCommand = schema.defaultCommand.schema.name;
59
+ result.commands = schema.commands.filter((cmd) => opts.includeHidden || !cmd.schema.hidden).map((cmd) => serializeCommand(cmd.schema, opts));
60
+ return result;
61
+ }
62
+ /**
63
+ * Serialize a single {@link CommandSchema} into a plain object.
64
+ *
65
+ * @param schema - The command schema to serialize.
66
+ * @param opts - Resolved generation options (hidden/prompt inclusion).
67
+ * @returns JSON-serializable object representing the command.
68
+ */
69
+ function serializeCommand(schema, opts) {
70
+ const result = { name: schema.name };
71
+ if (schema.description !== void 0) result.description = schema.description;
72
+ if (schema.aliases.length > 0) result.aliases = [...schema.aliases];
73
+ if (schema.hidden) result.hidden = true;
74
+ if (schema.examples.length > 0) result.examples = schema.examples.map(serializeExample);
75
+ const flags = {};
76
+ for (const [name, flagDef] of Object.entries(schema.flags)) flags[name] = serializeFlag(flagDef, opts);
77
+ result.flags = flags;
78
+ result.args = schema.args.map(serializeArgEntry);
79
+ result.commands = schema.commands.filter((cmd) => opts.includeHidden || !cmd.hidden).map((cmd) => serializeCommand(cmd, opts));
80
+ return result;
81
+ }
82
+ /**
83
+ * Serialize a {@link FlagSchema} into a plain object.
84
+ *
85
+ * @param schema - The flag schema to serialize.
86
+ * @param opts - Resolved generation options (prompt inclusion).
87
+ * @returns JSON-serializable object representing the flag.
88
+ */
89
+ function serializeFlag(schema, opts) {
90
+ const result = {
91
+ kind: schema.kind,
92
+ presence: schema.presence
93
+ };
94
+ if (schema.presence === "defaulted" && isJsonSerializable(schema.defaultValue)) result.defaultValue = schema.defaultValue;
95
+ const visibleAliases = getFlagAliasNames(schema);
96
+ if (visibleAliases.length > 0) result.aliases = [...visibleAliases];
97
+ if (schema.envVar !== void 0) result.envVar = schema.envVar;
98
+ if (schema.configPath !== void 0) result.configPath = schema.configPath;
99
+ if (schema.description !== void 0) result.description = schema.description;
100
+ if (schema.enumValues !== void 0) result.enumValues = [...schema.enumValues];
101
+ if (schema.elementSchema !== void 0) result.elementSchema = serializeFlag(schema.elementSchema, opts);
102
+ if (opts.includePrompts && schema.prompt !== void 0) result.prompt = serializePrompt(schema.prompt);
103
+ if (schema.deprecated !== void 0) result.deprecated = schema.deprecated;
104
+ if (schema.propagate) result.propagate = true;
105
+ return result;
106
+ }
107
+ /**
108
+ * Serialize a {@link CommandArgEntry} into a plain object.
109
+ *
110
+ * @param entry - The positional arg entry (name + {@link ArgSchema}).
111
+ * @returns JSON-serializable object representing the arg.
112
+ */
113
+ function serializeArgEntry(entry) {
114
+ const { name, schema } = entry;
115
+ const result = {
116
+ name,
117
+ kind: schema.kind,
118
+ presence: schema.presence
119
+ };
120
+ if (schema.variadic) result.variadic = true;
121
+ if (schema.stdinMode) result.stdinMode = true;
122
+ if (schema.presence === "defaulted" && isJsonSerializable(schema.defaultValue)) result.defaultValue = schema.defaultValue;
123
+ if (schema.description !== void 0) result.description = schema.description;
124
+ if (schema.envVar !== void 0) result.envVar = schema.envVar;
125
+ if (schema.enumValues !== void 0) result.enumValues = [...schema.enumValues];
126
+ if (schema.deprecated !== void 0) result.deprecated = schema.deprecated;
127
+ return result;
128
+ }
129
+ /**
130
+ * Serialize a {@link PromptConfig} into a plain object.
131
+ *
132
+ * @param prompt - The prompt configuration to serialize.
133
+ * @returns JSON-serializable object representing the prompt.
134
+ */
135
+ function serializePrompt(prompt) {
136
+ const result = {
137
+ kind: prompt.kind,
138
+ message: prompt.message
139
+ };
140
+ switch (prompt.kind) {
141
+ case "input":
142
+ if (prompt.placeholder !== void 0) result.placeholder = prompt.placeholder;
143
+ break;
144
+ case "select":
145
+ if (prompt.choices !== void 0) result.choices = prompt.choices.map(serializeChoice);
146
+ break;
147
+ case "multiselect":
148
+ if (prompt.choices !== void 0) result.choices = prompt.choices.map(serializeChoice);
149
+ if (prompt.min !== void 0) result.min = prompt.min;
150
+ if (prompt.max !== void 0) result.max = prompt.max;
151
+ break;
152
+ case "confirm": break;
153
+ }
154
+ return result;
155
+ }
156
+ /**
157
+ * Serialize a {@link SelectChoice} into a plain object.
158
+ *
159
+ * @param choice - The select/multiselect choice to serialize.
160
+ * @returns JSON-serializable object with value, optional label and description.
161
+ */
162
+ function serializeChoice(choice) {
163
+ const result = { value: choice.value };
164
+ if (choice.label !== void 0) result.label = choice.label;
165
+ if (choice.description !== void 0) result.description = choice.description;
166
+ return result;
167
+ }
168
+ /**
169
+ * Serialize a {@link CommandExample} into a plain object.
170
+ *
171
+ * @param example - The example to serialize.
172
+ * @returns JSON-serializable object with command and optional description.
173
+ */
174
+ function serializeExample(example) {
175
+ const result = { command: example.command };
176
+ if (example.description !== void 0) result.description = example.description;
177
+ return result;
178
+ }
179
+ /**
180
+ * Generate a JSON Schema (draft 2020-12) for validating CLI input as JSON.
181
+ *
182
+ * Accepts either a full {@link CLISchema} (producing a discriminated union
183
+ * across all commands) or a single {@link CommandSchema} (producing a flat
184
+ * object schema for that command's flags and args).
185
+ *
186
+ * **Single command** — produces an object schema where flag/arg names are
187
+ * properties with appropriate JSON Schema types.
188
+ *
189
+ * **Multi-command CLI** — produces a `oneOf` discriminated union with a
190
+ * `command` property identifying each branch. Nested subcommands use
191
+ * dot-delimited paths (e.g. `"deploy.rollback"`).
192
+ *
193
+ * Only commands with action handlers are included (group commands without
194
+ * actions are not directly invocable and are skipped).
195
+ *
196
+ * @param schema - A CLI schema or a single command schema.
197
+ * @param options - Generation options.
198
+ * @returns A JSON Schema object suitable for `JSON.stringify()`.
199
+ *
200
+ * @example
201
+ * ```ts
202
+ * // Validate a config file against the CLI's input shape
203
+ * const inputSchema = generateInputSchema(app.schema);
204
+ * writeFileSync('input-schema.json', JSON.stringify(inputSchema, null, 2));
205
+ * ```
206
+ */
207
+ function generateInputSchema(schema, options) {
208
+ const opts = resolveOptions(options);
209
+ if (isCommandSchema(schema)) return {
210
+ $schema: JSON_SCHEMA_DRAFT,
211
+ ...commandToInputSchema(schema)
212
+ };
213
+ const branches = [];
214
+ for (const cmd of schema.commands) {
215
+ if (!opts.includeHidden && cmd.schema.hidden) continue;
216
+ collectInputBranches(cmd.schema, "", branches, opts);
217
+ }
218
+ if (branches.length === 1) return {
219
+ $schema: JSON_SCHEMA_DRAFT,
220
+ ...stripCommandDiscriminator(branches[0] ?? {})
221
+ };
222
+ if (branches.length > 0) {
223
+ const defaultBranchName = schema.defaultCommand !== void 0 && (opts.includeHidden || !schema.defaultCommand.schema.hidden) ? schema.defaultCommand.schema.name : void 0;
224
+ return {
225
+ $schema: JSON_SCHEMA_DRAFT,
226
+ oneOf: defaultBranchName !== void 0 ? branches.map((branch) => getBranchCommandDiscriminator(branch) === defaultBranchName ? stripCommandDiscriminator(branch) : branch) : branches
227
+ };
228
+ }
229
+ return {
230
+ $schema: JSON_SCHEMA_DRAFT,
231
+ type: "object"
232
+ };
233
+ }
234
+ /**
235
+ * Discriminate between CLISchema and CommandSchema at runtime.
236
+ *
237
+ * Use a command-only field combination rather than a single shape check:
238
+ * command schemas always carry flags, args, middleware, and hasAction, while
239
+ * the CLI root schema does not expose that execution surface.
240
+ */
241
+ function isCommandSchema(schema) {
242
+ return "flags" in schema && "args" in schema && "middleware" in schema && "hasAction" in schema;
243
+ }
244
+ /** Recursively collect input schema branches for all invocable commands. */
245
+ function collectInputBranches(schema, prefix, branches, opts) {
246
+ const path = prefix ? `${prefix}.${schema.name}` : schema.name;
247
+ if (schema.hasAction) branches.push(commandToInputSchema(schema, path));
248
+ for (const sub of schema.commands) {
249
+ if (!opts.includeHidden && sub.hidden) continue;
250
+ collectInputBranches(sub, path, branches, opts);
251
+ }
252
+ }
253
+ /**
254
+ * Create a JSON Schema object for a single command's flags + args.
255
+ *
256
+ * When `commandPath` is provided, a `command` const discriminator property
257
+ * is added and required (used in multi-command oneOf schemas).
258
+ */
259
+ function commandToInputSchema(schema, commandPath) {
260
+ const properties = {};
261
+ const required = [];
262
+ if (commandPath !== void 0) {
263
+ properties.command = { const: commandPath };
264
+ required.push("command");
265
+ }
266
+ for (const [name, flagDef] of Object.entries(schema.flags)) {
267
+ properties[name] = flagToJsonSchemaType(flagDef);
268
+ if (flagDef.presence === "required") required.push(name);
269
+ }
270
+ for (const entry of schema.args) {
271
+ properties[entry.name] = argToJsonSchemaType(entry.schema);
272
+ if (entry.schema.presence === "required") required.push(entry.name);
273
+ }
274
+ const result = {
275
+ type: "object",
276
+ properties,
277
+ additionalProperties: false
278
+ };
279
+ if (required.length > 0) result.required = required;
280
+ return result;
281
+ }
282
+ /** @internal */
283
+ function stripCommandDiscriminator(branch) {
284
+ const propertiesValue = branch.properties;
285
+ const requiredValue = branch.required;
286
+ const properties = isRecord(propertiesValue) ? { ...propertiesValue } : void 0;
287
+ const required = Array.isArray(requiredValue) ? requiredValue.filter((value) => typeof value === "string") : void 0;
288
+ if (properties !== void 0) delete properties.command;
289
+ const cleanedRequired = required?.filter((value) => value !== "command");
290
+ const result = { ...branch };
291
+ if (properties !== void 0) result.properties = properties;
292
+ if (cleanedRequired !== void 0 && cleanedRequired.length > 0) result.required = cleanedRequired;
293
+ else delete result.required;
294
+ return result;
295
+ }
296
+ function getBranchCommandDiscriminator(branch) {
297
+ const propertiesValue = branch.properties;
298
+ if (!isRecord(propertiesValue)) return;
299
+ const commandValue = propertiesValue.command;
300
+ return isRecord(commandValue) && typeof commandValue.const === "string" ? commandValue.const : void 0;
301
+ }
302
+ function flagToJsonSchemaType(schema) {
303
+ const result = {};
304
+ switch (schema.kind) {
305
+ case "string":
306
+ result.type = "string";
307
+ break;
308
+ case "number": {
309
+ const constraints = schema.numberConstraints;
310
+ result.type = constraints?.int === true ? "integer" : "number";
311
+ if (constraints?.min !== void 0) result.minimum = constraints.min;
312
+ if (constraints?.max !== void 0) result.maximum = constraints.max;
313
+ break;
314
+ }
315
+ case "boolean":
316
+ result.type = "boolean";
317
+ break;
318
+ case "enum":
319
+ result.type = "string";
320
+ if (schema.enumValues !== void 0) result.enum = [...schema.enumValues];
321
+ break;
322
+ case "array":
323
+ result.type = "array";
324
+ if (schema.elementSchema !== void 0) result.items = flagToJsonSchemaType(schema.elementSchema);
325
+ break;
326
+ case "custom": break;
327
+ }
328
+ if (schema.description !== void 0) result.description = schema.description;
329
+ if (schema.presence === "defaulted" && isJsonSerializable(schema.defaultValue)) result.default = schema.defaultValue;
330
+ if (schema.deprecated !== void 0) result.deprecated = schema.deprecated;
331
+ return result;
332
+ }
333
+ function argToJsonSchemaType(schema) {
334
+ const kind = argKindToType(schema);
335
+ const result = schema.variadic ? {
336
+ type: "array",
337
+ items: kind
338
+ } : { ...kind };
339
+ if (schema.description !== void 0) result.description = schema.description;
340
+ if (schema.presence === "defaulted" && isJsonSerializable(schema.defaultValue)) result.default = schema.defaultValue;
341
+ if (schema.deprecated !== void 0) result.deprecated = schema.deprecated;
342
+ return result;
343
+ }
344
+ /** Map an arg's kind to a JSON Schema type fragment. */
345
+ function argKindToType(schema) {
346
+ switch (schema.kind) {
347
+ case "string": return { type: "string" };
348
+ case "number": {
349
+ const constraints = schema.numberConstraints;
350
+ const result = { type: constraints?.int === true ? "integer" : "number" };
351
+ if (constraints?.min !== void 0) result.minimum = constraints.min;
352
+ if (constraints?.max !== void 0) result.maximum = constraints.max;
353
+ return result;
354
+ }
355
+ case "enum": {
356
+ const result = { type: "string" };
357
+ if (schema.enumValues !== void 0) result.enum = [...schema.enumValues];
358
+ return result;
359
+ }
360
+ case "custom": return {};
361
+ }
362
+ }
363
+ /**
364
+ * Check whether a value can survive a JSON round-trip.
365
+ *
366
+ * Returns `false` for functions, symbols, bigints, non-finite numbers, and
367
+ * objects containing them. Used to guard default-value inclusion in
368
+ * serialized output.
369
+ */
370
+ function isJsonSerializable(value, seen = /* @__PURE__ */ new WeakSet()) {
371
+ if (value === void 0) return false;
372
+ if (value === null) return true;
373
+ const t = typeof value;
374
+ if (t === "string" || t === "boolean") return true;
375
+ if (t === "number") return Number.isFinite(value);
376
+ if (t === "function" || t === "symbol" || t === "bigint") return false;
377
+ if (Array.isArray(value)) {
378
+ if (seen.has(value)) return false;
379
+ seen.add(value);
380
+ try {
381
+ return value.every((entry) => isJsonSerializable(entry, seen));
382
+ } finally {
383
+ seen.delete(value);
384
+ }
385
+ }
386
+ if (t === "object") {
387
+ const objectValue = value;
388
+ if (!isPlainJsonObject(objectValue)) return false;
389
+ if (seen.has(objectValue)) return false;
390
+ seen.add(objectValue);
391
+ try {
392
+ return Object.values(objectValue).every((entry) => isJsonSerializable(entry, seen));
393
+ } finally {
394
+ seen.delete(objectValue);
395
+ }
396
+ }
397
+ return false;
398
+ }
399
+ /**
400
+ * Check whether an object is a plain JSON object.
401
+ *
402
+ * Accepts objects with `Object.prototype` or a null prototype, which are the
403
+ * only object shapes that round-trip through JSON as structural objects.
404
+ *
405
+ * @internal
406
+ */
407
+ function isPlainJsonObject(value) {
408
+ const proto = Object.getPrototypeOf(value);
409
+ return proto === Object.prototype || proto === null;
410
+ }
411
+ /** Convert a DSL string to a JSON Schema object definition. */
412
+ function def(source) {
413
+ return nodeToJsonSchema(parseSchema(source));
414
+ }
415
+ function withDefinitionDescriptions(schema, descriptions) {
416
+ const propertiesValue = schema.properties;
417
+ const describedProperties = typeof propertiesValue === "object" && propertiesValue !== null && isPlainJsonObject(propertiesValue) && descriptions.properties !== void 0 ? Object.fromEntries(Object.entries(propertiesValue).map(([name, propertySchema]) => {
418
+ const propertyDescriptions = descriptions.properties?.[name];
419
+ if (propertyDescriptions === void 0 || typeof propertySchema !== "object" || propertySchema === null || !isPlainJsonObject(propertySchema)) return [name, propertySchema];
420
+ return [name, withDefinitionDescriptions(propertySchema, propertyDescriptions)];
421
+ })) : void 0;
422
+ return {
423
+ ...schema,
424
+ ...descriptions.description !== void 0 ? { description: descriptions.description } : {},
425
+ ...describedProperties !== void 0 ? { properties: describedProperties } : {}
426
+ };
427
+ }
428
+ function withDefinitionMetaSchemaDescriptions(schema, descriptions) {
429
+ const describedRoot = withDefinitionDescriptions(schema, descriptions.root);
430
+ const defsValue = describedRoot.$defs;
431
+ if (typeof defsValue !== "object" || defsValue === null || !isPlainJsonObject(defsValue)) return describedRoot;
432
+ return {
433
+ ...describedRoot,
434
+ $defs: Object.fromEntries(Object.entries(defsValue).map(([name, defSchema]) => {
435
+ const defDescriptions = descriptions.defs[name];
436
+ if (defDescriptions === void 0 || typeof defSchema !== "object" || defSchema === null || !isPlainJsonObject(defSchema)) return [name, defSchema];
437
+ return [name, withDefinitionDescriptions(defSchema, defDescriptions)];
438
+ }))
439
+ };
440
+ }
441
+ /**
442
+ * JSON Schema (draft 2020-12) that validates the output of {@link generateSchema}.
443
+ *
444
+ * Each `$defs` entry is defined once as a schema DSL string — the DSL
445
+ * parser produces a runtime AST, and {@link nodeToJsonSchema} converts
446
+ * that AST to a JSON Schema fragment. No probe fixtures, no override
447
+ * maps, no manually maintained type definitions.
448
+ *
449
+ * Hosted at {@link DEFINITION_SCHEMA_URL} for `$schema` resolution. Also
450
+ * exported so tooling can validate definition documents without a network
451
+ * round-trip.
452
+ *
453
+ * @example
454
+ * ```ts
455
+ * import Ajv from 'ajv/dist/2020';
456
+ * import { definitionMetaSchema, generateSchema } from '@kjanat/dreamcli';
457
+ *
458
+ * const ajv = new Ajv();
459
+ * const validate = ajv.compile(definitionMetaSchema);
460
+ * const valid = validate(generateSchema(myCli.schema));
461
+ * ```
462
+ */
463
+ const definitionMetaSchema = withDefinitionMetaSchemaDescriptions({
464
+ $schema: JSON_SCHEMA_DRAFT,
465
+ $id: DEFINITION_SCHEMA_URL,
466
+ title: "@kjanat/dreamcli definition schema",
467
+ description: "Describes the structure of a CLI built with dreamcli — commands, flags, args, types, constraints, env bindings, and prompts.",
468
+ ...def(`{
469
+ $schema: '${DEFINITION_SCHEMA_URL}';
3
470
  name: string;
4
471
  version?: string;
5
472
  description?: string;
6
473
  defaultCommand?: string;
7
474
  commands: @command[]
8
- }`),$defs:{command:E(`{
475
+ }`),
476
+ $defs: {
477
+ command: def(`{
9
478
  name: string;
10
479
  description?: string;
11
480
  aliases?: string[];
@@ -14,7 +483,8 @@ import{getFlagAliasNames as e}from"../schema/flag.mjs";import{parseSchema as t}f
14
483
  flags: Record<string, @flag>;
15
484
  args: @arg[];
16
485
  commands: @command[]
17
- }`),flag:E(`{
486
+ }`),
487
+ flag: def(`{
18
488
  kind: 'string' | 'number' | 'boolean' | 'enum' | 'array' | 'custom';
19
489
  presence: 'optional' | 'required' | 'defaulted';
20
490
  defaultValue?: unknown;
@@ -27,7 +497,8 @@ import{getFlagAliasNames as e}from"../schema/flag.mjs";import{parseSchema as t}f
27
497
  prompt?: @prompt;
28
498
  deprecated?: string | true;
29
499
  propagate?: true
30
- }`),arg:E(`{
500
+ }`),
501
+ arg: def(`{
31
502
  name: string;
32
503
  kind: 'string' | 'number' | 'enum' | 'custom';
33
504
  presence: 'required' | 'optional' | 'defaulted';
@@ -38,18 +509,25 @@ import{getFlagAliasNames as e}from"../schema/flag.mjs";import{parseSchema as t}f
38
509
  envVar?: string;
39
510
  enumValues?: string[];
40
511
  deprecated?: string | true
41
- }`),prompt:E(`{
512
+ }`),
513
+ prompt: def(`{
42
514
  kind: 'confirm' | 'input' | 'select' | 'multiselect';
43
515
  message: string;
44
516
  placeholder?: string;
45
517
  choices?: @choice[];
46
518
  min?: integer;
47
519
  max?: integer
48
- }`),choice:E(`{
520
+ }`),
521
+ choice: def(`{
49
522
  value: string;
50
523
  label?: string;
51
524
  description?: string
52
- }`),example:E(`{
525
+ }`),
526
+ example: def(`{
53
527
  command: string;
54
528
  description?: string
55
- }`)}},r);export{k as definitionMetaSchema,h as generateInputSchema,c as generateSchema};
529
+ }`)
530
+ }
531
+ }, definitionMetaSchemaDescriptions);
532
+ //#endregion
533
+ export { definitionMetaSchema, generateInputSchema, generateSchema };