@kjanat/dreamcli 0.0.0 → 1.0.0
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 +667 -0
- package/LICENSE +22 -0
- package/README.md +370 -0
- package/dist/adapter-B37d9oia.mjs +1 -0
- package/dist/adapter-CCSh5juX.cjs +1 -0
- package/dist/adapter-DIwO-q7K.d.mts +3447 -0
- package/dist/adapter-DQnxxLiE.d.cts +3447 -0
- package/dist/auto-5cjZaF9V.mjs +3 -0
- package/dist/auto-B0eSgoDw.cjs +3 -0
- package/dist/index.cjs +10 -0
- package/dist/index.d.cts +920 -0
- package/dist/index.d.mts +920 -0
- package/dist/index.mjs +10 -0
- package/dist/runtime.cjs +1 -0
- package/dist/runtime.d.cts +253 -0
- package/dist/runtime.d.mts +253 -0
- package/dist/runtime.mjs +1 -0
- package/dist/testkit-CEDYPvhF.mjs +14 -0
- package/dist/testkit-ClIKijxC.cjs +14 -0
- package/dist/testkit.cjs +1 -0
- package/dist/testkit.d.cts +25 -0
- package/dist/testkit.d.mts +25 -0
- package/dist/testkit.mjs +1 -0
- package/examples/basic.ts +33 -0
- package/examples/gh/package.json +48 -0
- package/examples/gh/src/commands/auth.ts +66 -0
- package/examples/gh/src/commands/issue.ts +120 -0
- package/examples/gh/src/commands/pr.ts +125 -0
- package/examples/gh/src/data/issues.yaml +5 -0
- package/examples/gh/src/data/issues.yaml.d.ts +17 -0
- package/examples/gh/src/data/pull-requests.yaml +7 -0
- package/examples/gh/src/data/pull-requests.yaml.d.ts +18 -0
- package/examples/gh/src/lib/auth.ts +37 -0
- package/examples/gh/src/lib/utils.ts +17 -0
- package/examples/gh/src/main.test.ts +306 -0
- package/examples/gh/src/main.ts +38 -0
- package/examples/gh/tsconfig.json +37 -0
- package/examples/interactive.ts +66 -0
- package/examples/json-mode.ts +93 -0
- package/examples/middleware.ts +71 -0
- package/examples/multi-command.ts +66 -0
- package/examples/spinner-progress.ts +49 -0
- package/examples/testing.ts +145 -0
- package/examples/tsconfig.json +17 -0
- package/package.json +123 -2
- package/src/core/cli/AGENTS.md +72 -0
- package/src/core/cli/dispatch.ts +282 -0
- package/src/core/cli/index.ts +1425 -0
- package/src/core/cli/plugin.ts +111 -0
- package/src/core/cli/propagate.ts +97 -0
- package/src/core/cli/root-help.ts +269 -0
- package/src/core/cli/root-surface.ts +74 -0
- package/src/core/completion/AGENTS.md +72 -0
- package/src/core/completion/completion-test-helpers.ts +48 -0
- package/src/core/completion/index.ts +82 -0
- package/src/core/completion/shells/bash.ts +456 -0
- package/src/core/completion/shells/fish.ts +24 -0
- package/src/core/completion/shells/powershell.ts +24 -0
- package/src/core/completion/shells/shared.ts +283 -0
- package/src/core/completion/shells/zsh.ts +376 -0
- package/src/core/config/index.ts +404 -0
- package/src/core/config/package-json.ts +216 -0
- package/src/core/errors/index.ts +178 -0
- package/src/core/help/index.ts +559 -0
- package/src/core/json-schema/index.ts +705 -0
- package/src/core/output/AGENTS.md +69 -0
- package/src/core/output/activity.ts +568 -0
- package/src/core/output/display-value.ts +48 -0
- package/src/core/output/index.ts +704 -0
- package/src/core/output/writer.ts +46 -0
- package/src/core/parse/index.ts +643 -0
- package/src/core/prompt/index.ts +566 -0
- package/src/core/resolve/AGENTS.md +69 -0
- package/src/core/resolve/index.ts +1331 -0
- package/src/core/schema/AGENTS.md +61 -0
- package/src/core/schema/activity.ts +237 -0
- package/src/core/schema/arg.ts +707 -0
- package/src/core/schema/command.ts +1263 -0
- package/src/core/schema/flag.ts +651 -0
- package/src/core/schema/index.ts +82 -0
- package/src/core/schema/middleware.ts +171 -0
- package/src/core/schema/prompt.ts +148 -0
- package/src/core/schema/run.ts +187 -0
- package/src/core/testkit/AGENTS.md +55 -0
- package/src/core/testkit/index.ts +365 -0
- package/src/index.ts +164 -0
- package/src/runtime/AGENTS.md +74 -0
- package/src/runtime/adapter.ts +300 -0
- package/src/runtime/auto.ts +110 -0
- package/src/runtime/bun.ts +55 -0
- package/src/runtime/deno.ts +355 -0
- package/src/runtime/detect.ts +102 -0
- package/src/runtime/index.ts +21 -0
- package/src/runtime/node-builtins.d.ts +23 -0
- package/src/runtime/node.ts +278 -0
- package/src/runtime/paths.ts +56 -0
- package/src/runtime/support.ts +119 -0
- package/src/runtime/test-helpers.ts +40 -0
- package/src/runtime.ts +31 -0
- package/src/testkit.ts +23 -0
- package/src/version.ts +20 -0
|
@@ -0,0 +1,705 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* JSON Schema generation from CLI schemas.
|
|
3
|
+
*
|
|
4
|
+
* Two complementary functions:
|
|
5
|
+
*
|
|
6
|
+
* - {@link generateSchema} — definition metadata describing the CLI tree
|
|
7
|
+
* (commands, flags, args, types, constraints) for tooling and documentation.
|
|
8
|
+
*
|
|
9
|
+
* - {@link generateInputSchema} — JSON Schema (draft 2020-12) for validating
|
|
10
|
+
* CLI input as a JSON object, useful for config file validation and IDE
|
|
11
|
+
* autocompletion.
|
|
12
|
+
*
|
|
13
|
+
* @module dreamcli/core/json-schema
|
|
14
|
+
*/
|
|
15
|
+
|
|
16
|
+
import type { CLISchema } from '#internals/core/cli/index.ts';
|
|
17
|
+
import type {
|
|
18
|
+
ArgSchema,
|
|
19
|
+
CommandArgEntry,
|
|
20
|
+
CommandExample,
|
|
21
|
+
CommandSchema,
|
|
22
|
+
FlagSchema,
|
|
23
|
+
PromptConfig,
|
|
24
|
+
SelectChoice,
|
|
25
|
+
} from '#internals/core/schema/index.ts';
|
|
26
|
+
|
|
27
|
+
// --- Options
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* Options for JSON Schema generation.
|
|
31
|
+
*
|
|
32
|
+
* Both {@link generateSchema} and {@link generateInputSchema} accept these
|
|
33
|
+
* options to control which parts of the CLI schema are included in the output.
|
|
34
|
+
*/
|
|
35
|
+
interface JsonSchemaOptions {
|
|
36
|
+
/**
|
|
37
|
+
* Include commands marked as hidden.
|
|
38
|
+
*
|
|
39
|
+
* When `true` (default), hidden commands appear in the output with
|
|
40
|
+
* `hidden: true` (definition schema) or as valid branches (input schema).
|
|
41
|
+
* When `false`, hidden commands and their entire subtrees are excluded.
|
|
42
|
+
*
|
|
43
|
+
* @defaultValue `true`
|
|
44
|
+
*/
|
|
45
|
+
readonly includeHidden?: boolean;
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* Include prompt configuration on flags.
|
|
49
|
+
*
|
|
50
|
+
* When `false`, prompt configs are omitted even if defined on flags.
|
|
51
|
+
* Useful for producing a schema focused on the non-interactive CLI
|
|
52
|
+
* surface only.
|
|
53
|
+
*
|
|
54
|
+
* Only affects {@link generateSchema} output — prompt configs are never
|
|
55
|
+
* included in {@link generateInputSchema} output.
|
|
56
|
+
*
|
|
57
|
+
* @defaultValue `true`
|
|
58
|
+
*/
|
|
59
|
+
readonly includePrompts?: boolean;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/** Internal resolved options with defaults applied. */
|
|
63
|
+
interface ResolvedOptions {
|
|
64
|
+
readonly includeHidden: boolean;
|
|
65
|
+
readonly includePrompts: boolean;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Apply defaults to optional {@link JsonSchemaOptions}.
|
|
70
|
+
*
|
|
71
|
+
* @param options - User-supplied schema generation options, or `undefined` for all defaults.
|
|
72
|
+
* @returns Fully resolved options with defaults applied.
|
|
73
|
+
*/
|
|
74
|
+
function resolveOptions(options: JsonSchemaOptions | undefined): ResolvedOptions {
|
|
75
|
+
return {
|
|
76
|
+
includeHidden: options?.includeHidden ?? true,
|
|
77
|
+
includePrompts: options?.includePrompts ?? true,
|
|
78
|
+
};
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
// --- Constants
|
|
82
|
+
|
|
83
|
+
/** Meta-schema URL for the definition schema format. */
|
|
84
|
+
const DEFINITION_SCHEMA_URL = 'https://dreamcli.kjanat.com/schemas/cli/v1.json';
|
|
85
|
+
|
|
86
|
+
/** Meta-schema URL for JSON Schema draft 2020-12 (input validation). */
|
|
87
|
+
const JSON_SCHEMA_DRAFT = 'https://json-schema.org/draft/2020-12/schema';
|
|
88
|
+
|
|
89
|
+
function isRecord(value: unknown): value is Record<string, unknown> {
|
|
90
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
// === Definition schema — generateSchema()
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* Generate a definition metadata document describing the CLI's structure.
|
|
97
|
+
*
|
|
98
|
+
* Walks the full command tree and produces a plain JSON-serializable object
|
|
99
|
+
* representing all commands, subcommands, flags, args, and metadata.
|
|
100
|
+
* Non-serializable runtime values (parse functions, middleware handlers,
|
|
101
|
+
* interactive resolvers) are omitted.
|
|
102
|
+
*
|
|
103
|
+
* @param schema - The CLI schema from `CLIBuilder.schema`.
|
|
104
|
+
* @param options - Generation options.
|
|
105
|
+
* @returns A plain object suitable for `JSON.stringify()`.
|
|
106
|
+
*
|
|
107
|
+
* @example
|
|
108
|
+
* ```ts
|
|
109
|
+
* const app = cli('myapp').version('1.0.0').command(deploy);
|
|
110
|
+
* const definition = generateSchema(app.schema);
|
|
111
|
+
* writeFileSync('cli-schema.json', JSON.stringify(definition, null, 2));
|
|
112
|
+
* ```
|
|
113
|
+
*/
|
|
114
|
+
function generateSchema(schema: CLISchema, options?: JsonSchemaOptions): Record<string, unknown> {
|
|
115
|
+
const opts = resolveOptions(options);
|
|
116
|
+
|
|
117
|
+
const result: Record<string, unknown> = {
|
|
118
|
+
$schema: DEFINITION_SCHEMA_URL,
|
|
119
|
+
name: schema.name,
|
|
120
|
+
};
|
|
121
|
+
|
|
122
|
+
if (schema.version !== undefined) {
|
|
123
|
+
result.version = schema.version;
|
|
124
|
+
}
|
|
125
|
+
if (schema.description !== undefined) {
|
|
126
|
+
result.description = schema.description;
|
|
127
|
+
}
|
|
128
|
+
if (
|
|
129
|
+
schema.defaultCommand !== undefined &&
|
|
130
|
+
(opts.includeHidden || !schema.defaultCommand.schema.hidden)
|
|
131
|
+
) {
|
|
132
|
+
result.defaultCommand = schema.defaultCommand.schema.name;
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
result.commands = schema.commands
|
|
136
|
+
.filter((cmd) => opts.includeHidden || !cmd.schema.hidden)
|
|
137
|
+
.map((cmd) => serializeCommand(cmd.schema, opts));
|
|
138
|
+
|
|
139
|
+
return result;
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
// --- Command serialization
|
|
143
|
+
|
|
144
|
+
/**
|
|
145
|
+
* Serialize a single {@link CommandSchema} into a plain object.
|
|
146
|
+
*
|
|
147
|
+
* @param schema - The command schema to serialize.
|
|
148
|
+
* @param opts - Resolved generation options (hidden/prompt inclusion).
|
|
149
|
+
* @returns JSON-serializable object representing the command.
|
|
150
|
+
*/
|
|
151
|
+
function serializeCommand(schema: CommandSchema, opts: ResolvedOptions): Record<string, unknown> {
|
|
152
|
+
const result: Record<string, unknown> = { name: schema.name };
|
|
153
|
+
|
|
154
|
+
if (schema.description !== undefined) {
|
|
155
|
+
result.description = schema.description;
|
|
156
|
+
}
|
|
157
|
+
if (schema.aliases.length > 0) {
|
|
158
|
+
result.aliases = [...schema.aliases];
|
|
159
|
+
}
|
|
160
|
+
if (schema.hidden) {
|
|
161
|
+
result.hidden = true;
|
|
162
|
+
}
|
|
163
|
+
if (schema.examples.length > 0) {
|
|
164
|
+
result.examples = schema.examples.map(serializeExample);
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
// Flags — always present (consumers iterate without existence check)
|
|
168
|
+
const flags: Record<string, Record<string, unknown>> = {};
|
|
169
|
+
for (const [name, flagDef] of Object.entries(schema.flags)) {
|
|
170
|
+
flags[name] = serializeFlag(flagDef, opts);
|
|
171
|
+
}
|
|
172
|
+
result.flags = flags;
|
|
173
|
+
|
|
174
|
+
// Args — always present (positional order matters)
|
|
175
|
+
result.args = schema.args.map(serializeArgEntry);
|
|
176
|
+
|
|
177
|
+
// Subcommands — always present
|
|
178
|
+
result.commands = schema.commands
|
|
179
|
+
.filter((cmd) => opts.includeHidden || !cmd.hidden)
|
|
180
|
+
.map((cmd) => serializeCommand(cmd, opts));
|
|
181
|
+
|
|
182
|
+
return result;
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
// --- Flag serialization
|
|
186
|
+
|
|
187
|
+
/**
|
|
188
|
+
* Serialize a {@link FlagSchema} into a plain object.
|
|
189
|
+
*
|
|
190
|
+
* @param schema - The flag schema to serialize.
|
|
191
|
+
* @param opts - Resolved generation options (prompt inclusion).
|
|
192
|
+
* @returns JSON-serializable object representing the flag.
|
|
193
|
+
*/
|
|
194
|
+
function serializeFlag(schema: FlagSchema, opts: ResolvedOptions): Record<string, unknown> {
|
|
195
|
+
const result: Record<string, unknown> = {
|
|
196
|
+
kind: schema.kind,
|
|
197
|
+
presence: schema.presence,
|
|
198
|
+
};
|
|
199
|
+
|
|
200
|
+
if (schema.presence === 'defaulted' && isJsonSerializable(schema.defaultValue)) {
|
|
201
|
+
result.defaultValue = schema.defaultValue;
|
|
202
|
+
}
|
|
203
|
+
if (schema.aliases.length > 0) {
|
|
204
|
+
result.aliases = [...schema.aliases];
|
|
205
|
+
}
|
|
206
|
+
if (schema.envVar !== undefined) {
|
|
207
|
+
result.envVar = schema.envVar;
|
|
208
|
+
}
|
|
209
|
+
if (schema.configPath !== undefined) {
|
|
210
|
+
result.configPath = schema.configPath;
|
|
211
|
+
}
|
|
212
|
+
if (schema.description !== undefined) {
|
|
213
|
+
result.description = schema.description;
|
|
214
|
+
}
|
|
215
|
+
if (schema.enumValues !== undefined) {
|
|
216
|
+
result.enumValues = [...schema.enumValues];
|
|
217
|
+
}
|
|
218
|
+
if (schema.elementSchema !== undefined) {
|
|
219
|
+
result.elementSchema = serializeFlag(schema.elementSchema, opts);
|
|
220
|
+
}
|
|
221
|
+
if (opts.includePrompts && schema.prompt !== undefined) {
|
|
222
|
+
result.prompt = serializePrompt(schema.prompt);
|
|
223
|
+
}
|
|
224
|
+
if (schema.deprecated !== undefined) {
|
|
225
|
+
result.deprecated = schema.deprecated;
|
|
226
|
+
}
|
|
227
|
+
if (schema.propagate) {
|
|
228
|
+
result.propagate = true;
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
return result;
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
// --- Arg serialization
|
|
235
|
+
|
|
236
|
+
/**
|
|
237
|
+
* Serialize a {@link CommandArgEntry} into a plain object.
|
|
238
|
+
*
|
|
239
|
+
* @param entry - The positional arg entry (name + {@link ArgSchema}).
|
|
240
|
+
* @returns JSON-serializable object representing the arg.
|
|
241
|
+
*/
|
|
242
|
+
function serializeArgEntry(entry: CommandArgEntry): Record<string, unknown> {
|
|
243
|
+
const { name, schema } = entry;
|
|
244
|
+
const result: Record<string, unknown> = {
|
|
245
|
+
name,
|
|
246
|
+
kind: schema.kind,
|
|
247
|
+
presence: schema.presence,
|
|
248
|
+
};
|
|
249
|
+
|
|
250
|
+
if (schema.variadic) {
|
|
251
|
+
result.variadic = true;
|
|
252
|
+
}
|
|
253
|
+
if (schema.stdinMode) {
|
|
254
|
+
result.stdinMode = true;
|
|
255
|
+
}
|
|
256
|
+
if (schema.presence === 'defaulted' && isJsonSerializable(schema.defaultValue)) {
|
|
257
|
+
result.defaultValue = schema.defaultValue;
|
|
258
|
+
}
|
|
259
|
+
if (schema.description !== undefined) {
|
|
260
|
+
result.description = schema.description;
|
|
261
|
+
}
|
|
262
|
+
if (schema.envVar !== undefined) {
|
|
263
|
+
result.envVar = schema.envVar;
|
|
264
|
+
}
|
|
265
|
+
if (schema.enumValues !== undefined) {
|
|
266
|
+
result.enumValues = [...schema.enumValues];
|
|
267
|
+
}
|
|
268
|
+
if (schema.deprecated !== undefined) {
|
|
269
|
+
result.deprecated = schema.deprecated;
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
return result;
|
|
273
|
+
}
|
|
274
|
+
|
|
275
|
+
// --- Prompt serialization
|
|
276
|
+
|
|
277
|
+
/**
|
|
278
|
+
* Serialize a {@link PromptConfig} into a plain object.
|
|
279
|
+
*
|
|
280
|
+
* @param prompt - The prompt configuration to serialize.
|
|
281
|
+
* @returns JSON-serializable object representing the prompt.
|
|
282
|
+
*/
|
|
283
|
+
function serializePrompt(prompt: PromptConfig): Record<string, unknown> {
|
|
284
|
+
const result: Record<string, unknown> = {
|
|
285
|
+
kind: prompt.kind,
|
|
286
|
+
message: prompt.message,
|
|
287
|
+
};
|
|
288
|
+
|
|
289
|
+
switch (prompt.kind) {
|
|
290
|
+
case 'input':
|
|
291
|
+
if (prompt.placeholder !== undefined) {
|
|
292
|
+
result.placeholder = prompt.placeholder;
|
|
293
|
+
}
|
|
294
|
+
// validate fn omitted — not serializable
|
|
295
|
+
break;
|
|
296
|
+
case 'select':
|
|
297
|
+
if (prompt.choices !== undefined) {
|
|
298
|
+
result.choices = prompt.choices.map(serializeChoice);
|
|
299
|
+
}
|
|
300
|
+
break;
|
|
301
|
+
case 'multiselect':
|
|
302
|
+
if (prompt.choices !== undefined) {
|
|
303
|
+
result.choices = prompt.choices.map(serializeChoice);
|
|
304
|
+
}
|
|
305
|
+
if (prompt.min !== undefined) {
|
|
306
|
+
result.min = prompt.min;
|
|
307
|
+
}
|
|
308
|
+
if (prompt.max !== undefined) {
|
|
309
|
+
result.max = prompt.max;
|
|
310
|
+
}
|
|
311
|
+
break;
|
|
312
|
+
case 'confirm':
|
|
313
|
+
break;
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
return result;
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
/**
|
|
320
|
+
* Serialize a {@link SelectChoice} into a plain object.
|
|
321
|
+
*
|
|
322
|
+
* @param choice - The select/multiselect choice to serialize.
|
|
323
|
+
* @returns JSON-serializable object with value, optional label and description.
|
|
324
|
+
*/
|
|
325
|
+
function serializeChoice(choice: SelectChoice): Record<string, unknown> {
|
|
326
|
+
const result: Record<string, unknown> = { value: choice.value };
|
|
327
|
+
if (choice.label !== undefined) {
|
|
328
|
+
result.label = choice.label;
|
|
329
|
+
}
|
|
330
|
+
if (choice.description !== undefined) {
|
|
331
|
+
result.description = choice.description;
|
|
332
|
+
}
|
|
333
|
+
return result;
|
|
334
|
+
}
|
|
335
|
+
|
|
336
|
+
// --- Example serialization
|
|
337
|
+
|
|
338
|
+
/**
|
|
339
|
+
* Serialize a {@link CommandExample} into a plain object.
|
|
340
|
+
*
|
|
341
|
+
* @param example - The example to serialize.
|
|
342
|
+
* @returns JSON-serializable object with command and optional description.
|
|
343
|
+
*/
|
|
344
|
+
function serializeExample(example: CommandExample): Record<string, unknown> {
|
|
345
|
+
const result: Record<string, unknown> = { command: example.command };
|
|
346
|
+
if (example.description !== undefined) {
|
|
347
|
+
result.description = example.description;
|
|
348
|
+
}
|
|
349
|
+
return result;
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
// === Input validation schema — generateInputSchema()
|
|
353
|
+
|
|
354
|
+
/**
|
|
355
|
+
* Generate a JSON Schema (draft 2020-12) for validating CLI input as JSON.
|
|
356
|
+
*
|
|
357
|
+
* Accepts either a full {@link CLISchema} (producing a discriminated union
|
|
358
|
+
* across all commands) or a single {@link CommandSchema} (producing a flat
|
|
359
|
+
* object schema for that command's flags and args).
|
|
360
|
+
*
|
|
361
|
+
* **Single command** — produces an object schema where flag/arg names are
|
|
362
|
+
* properties with appropriate JSON Schema types.
|
|
363
|
+
*
|
|
364
|
+
* **Multi-command CLI** — produces a `oneOf` discriminated union with a
|
|
365
|
+
* `command` property identifying each branch. Nested subcommands use
|
|
366
|
+
* dot-delimited paths (e.g. `"deploy.rollback"`).
|
|
367
|
+
*
|
|
368
|
+
* Only commands with action handlers are included (group commands without
|
|
369
|
+
* actions are not directly invocable and are skipped).
|
|
370
|
+
*
|
|
371
|
+
* @param schema - A CLI schema or a single command schema.
|
|
372
|
+
* @param options - Generation options.
|
|
373
|
+
* @returns A JSON Schema object suitable for `JSON.stringify()`.
|
|
374
|
+
*
|
|
375
|
+
* @example
|
|
376
|
+
* ```ts
|
|
377
|
+
* // Validate a config file against the CLI's input shape
|
|
378
|
+
* const inputSchema = generateInputSchema(app.schema);
|
|
379
|
+
* writeFileSync('input-schema.json', JSON.stringify(inputSchema, null, 2));
|
|
380
|
+
* ```
|
|
381
|
+
*/
|
|
382
|
+
function generateInputSchema(
|
|
383
|
+
schema: CLISchema | CommandSchema,
|
|
384
|
+
options?: JsonSchemaOptions,
|
|
385
|
+
): Record<string, unknown> {
|
|
386
|
+
const opts = resolveOptions(options);
|
|
387
|
+
|
|
388
|
+
// Discriminate between a leaf/group command schema and the CLI root schema.
|
|
389
|
+
if (isCommandSchema(schema)) {
|
|
390
|
+
return {
|
|
391
|
+
$schema: JSON_SCHEMA_DRAFT,
|
|
392
|
+
...commandToInputSchema(schema),
|
|
393
|
+
};
|
|
394
|
+
}
|
|
395
|
+
|
|
396
|
+
// CLISchema — collect all invocable commands into branches
|
|
397
|
+
const branches: Array<Record<string, unknown>> = [];
|
|
398
|
+
for (const cmd of schema.commands) {
|
|
399
|
+
if (!opts.includeHidden && cmd.schema.hidden) continue;
|
|
400
|
+
collectInputBranches(cmd.schema, '', branches, opts);
|
|
401
|
+
}
|
|
402
|
+
|
|
403
|
+
// Single branch: emit flat (no oneOf wrapper)
|
|
404
|
+
if (branches.length === 1) {
|
|
405
|
+
const branch = stripCommandDiscriminator(branches[0] ?? {});
|
|
406
|
+
return {
|
|
407
|
+
$schema: JSON_SCHEMA_DRAFT,
|
|
408
|
+
...branch,
|
|
409
|
+
};
|
|
410
|
+
}
|
|
411
|
+
|
|
412
|
+
// Multiple branches: discriminated union
|
|
413
|
+
if (branches.length > 0) {
|
|
414
|
+
const defaultBranchName =
|
|
415
|
+
schema.defaultCommand !== undefined &&
|
|
416
|
+
(opts.includeHidden || !schema.defaultCommand.schema.hidden)
|
|
417
|
+
? schema.defaultCommand.schema.name
|
|
418
|
+
: undefined;
|
|
419
|
+
const normalizedBranches =
|
|
420
|
+
defaultBranchName !== undefined
|
|
421
|
+
? branches.map((branch) =>
|
|
422
|
+
getBranchCommandDiscriminator(branch) === defaultBranchName
|
|
423
|
+
? stripCommandDiscriminator(branch)
|
|
424
|
+
: branch,
|
|
425
|
+
)
|
|
426
|
+
: branches;
|
|
427
|
+
|
|
428
|
+
return {
|
|
429
|
+
$schema: JSON_SCHEMA_DRAFT,
|
|
430
|
+
oneOf: normalizedBranches,
|
|
431
|
+
};
|
|
432
|
+
}
|
|
433
|
+
|
|
434
|
+
// No invocable commands
|
|
435
|
+
return {
|
|
436
|
+
$schema: JSON_SCHEMA_DRAFT,
|
|
437
|
+
type: 'object',
|
|
438
|
+
};
|
|
439
|
+
}
|
|
440
|
+
|
|
441
|
+
// --- Input schema helpers
|
|
442
|
+
|
|
443
|
+
/**
|
|
444
|
+
* Discriminate between CLISchema and CommandSchema at runtime.
|
|
445
|
+
*
|
|
446
|
+
* Use a command-only field combination rather than a single shape check:
|
|
447
|
+
* command schemas always carry flags, args, middleware, and hasAction, while
|
|
448
|
+
* the CLI root schema does not expose that execution surface.
|
|
449
|
+
*/
|
|
450
|
+
function isCommandSchema(schema: CLISchema | CommandSchema): schema is CommandSchema {
|
|
451
|
+
return 'flags' in schema && 'args' in schema && 'middleware' in schema && 'hasAction' in schema;
|
|
452
|
+
}
|
|
453
|
+
|
|
454
|
+
/** Recursively collect input schema branches for all invocable commands. */
|
|
455
|
+
function collectInputBranches(
|
|
456
|
+
schema: CommandSchema,
|
|
457
|
+
prefix: string,
|
|
458
|
+
branches: Array<Record<string, unknown>>,
|
|
459
|
+
opts: ResolvedOptions,
|
|
460
|
+
): void {
|
|
461
|
+
const path = prefix ? `${prefix}.${schema.name}` : schema.name;
|
|
462
|
+
|
|
463
|
+
if (schema.hasAction) {
|
|
464
|
+
branches.push(commandToInputSchema(schema, path));
|
|
465
|
+
}
|
|
466
|
+
|
|
467
|
+
for (const sub of schema.commands) {
|
|
468
|
+
if (!opts.includeHidden && sub.hidden) continue;
|
|
469
|
+
collectInputBranches(sub, path, branches, opts);
|
|
470
|
+
}
|
|
471
|
+
}
|
|
472
|
+
|
|
473
|
+
/**
|
|
474
|
+
* Create a JSON Schema object for a single command's flags + args.
|
|
475
|
+
*
|
|
476
|
+
* When `commandPath` is provided, a `command` const discriminator property
|
|
477
|
+
* is added and required (used in multi-command oneOf schemas).
|
|
478
|
+
*/
|
|
479
|
+
function commandToInputSchema(
|
|
480
|
+
schema: CommandSchema,
|
|
481
|
+
commandPath?: string,
|
|
482
|
+
): Record<string, unknown> {
|
|
483
|
+
const properties: Record<string, Record<string, unknown>> = {};
|
|
484
|
+
const required: string[] = [];
|
|
485
|
+
|
|
486
|
+
// Command discriminator (for multi-command schemas)
|
|
487
|
+
if (commandPath !== undefined) {
|
|
488
|
+
properties.command = { const: commandPath };
|
|
489
|
+
required.push('command');
|
|
490
|
+
}
|
|
491
|
+
|
|
492
|
+
// Flags → properties
|
|
493
|
+
for (const [name, flagDef] of Object.entries(schema.flags)) {
|
|
494
|
+
properties[name] = flagToJsonSchemaType(flagDef);
|
|
495
|
+
if (flagDef.presence === 'required') {
|
|
496
|
+
required.push(name);
|
|
497
|
+
}
|
|
498
|
+
}
|
|
499
|
+
|
|
500
|
+
// Args → properties (by name)
|
|
501
|
+
for (const entry of schema.args) {
|
|
502
|
+
properties[entry.name] = argToJsonSchemaType(entry.schema);
|
|
503
|
+
if (entry.schema.presence === 'required') {
|
|
504
|
+
required.push(entry.name);
|
|
505
|
+
}
|
|
506
|
+
}
|
|
507
|
+
|
|
508
|
+
const result: Record<string, unknown> = {
|
|
509
|
+
type: 'object',
|
|
510
|
+
properties,
|
|
511
|
+
additionalProperties: false,
|
|
512
|
+
};
|
|
513
|
+
|
|
514
|
+
if (required.length > 0) {
|
|
515
|
+
result.required = required;
|
|
516
|
+
}
|
|
517
|
+
|
|
518
|
+
return result;
|
|
519
|
+
}
|
|
520
|
+
|
|
521
|
+
/** @internal */
|
|
522
|
+
function stripCommandDiscriminator(branch: Record<string, unknown>): Record<string, unknown> {
|
|
523
|
+
const propertiesValue = branch.properties;
|
|
524
|
+
const requiredValue = branch.required;
|
|
525
|
+
const properties = isRecord(propertiesValue) ? { ...propertiesValue } : undefined;
|
|
526
|
+
const required = Array.isArray(requiredValue)
|
|
527
|
+
? requiredValue.filter((value): value is string => typeof value === 'string')
|
|
528
|
+
: undefined;
|
|
529
|
+
|
|
530
|
+
if (properties !== undefined) {
|
|
531
|
+
delete properties.command;
|
|
532
|
+
}
|
|
533
|
+
|
|
534
|
+
const cleanedRequired = required?.filter((value) => value !== 'command');
|
|
535
|
+
const result: Record<string, unknown> = { ...branch };
|
|
536
|
+
|
|
537
|
+
if (properties !== undefined) {
|
|
538
|
+
result.properties = properties;
|
|
539
|
+
}
|
|
540
|
+
|
|
541
|
+
if (cleanedRequired !== undefined && cleanedRequired.length > 0) {
|
|
542
|
+
result.required = cleanedRequired;
|
|
543
|
+
} else {
|
|
544
|
+
delete result.required;
|
|
545
|
+
}
|
|
546
|
+
|
|
547
|
+
return result;
|
|
548
|
+
}
|
|
549
|
+
|
|
550
|
+
function getBranchCommandDiscriminator(branch: Record<string, unknown>): string | undefined {
|
|
551
|
+
const propertiesValue = branch.properties;
|
|
552
|
+
if (!isRecord(propertiesValue)) {
|
|
553
|
+
return undefined;
|
|
554
|
+
}
|
|
555
|
+
|
|
556
|
+
const commandValue = propertiesValue.command;
|
|
557
|
+
return isRecord(commandValue) && typeof commandValue.const === 'string'
|
|
558
|
+
? commandValue.const
|
|
559
|
+
: undefined;
|
|
560
|
+
}
|
|
561
|
+
|
|
562
|
+
// --- Type mapping — flags → JSON Schema types
|
|
563
|
+
|
|
564
|
+
function flagToJsonSchemaType(schema: FlagSchema): Record<string, unknown> {
|
|
565
|
+
const result: Record<string, unknown> = {};
|
|
566
|
+
|
|
567
|
+
switch (schema.kind) {
|
|
568
|
+
case 'string':
|
|
569
|
+
result.type = 'string';
|
|
570
|
+
break;
|
|
571
|
+
case 'number':
|
|
572
|
+
result.type = 'number';
|
|
573
|
+
break;
|
|
574
|
+
case 'boolean':
|
|
575
|
+
result.type = 'boolean';
|
|
576
|
+
break;
|
|
577
|
+
case 'enum':
|
|
578
|
+
result.type = 'string';
|
|
579
|
+
if (schema.enumValues !== undefined) {
|
|
580
|
+
result.enum = [...schema.enumValues];
|
|
581
|
+
}
|
|
582
|
+
break;
|
|
583
|
+
case 'array':
|
|
584
|
+
result.type = 'array';
|
|
585
|
+
if (schema.elementSchema !== undefined) {
|
|
586
|
+
result.items = flagToJsonSchemaType(schema.elementSchema);
|
|
587
|
+
}
|
|
588
|
+
break;
|
|
589
|
+
case 'custom':
|
|
590
|
+
// Opaque type — no JSON Schema constraint
|
|
591
|
+
break;
|
|
592
|
+
}
|
|
593
|
+
|
|
594
|
+
if (schema.description !== undefined) {
|
|
595
|
+
result.description = schema.description;
|
|
596
|
+
}
|
|
597
|
+
if (schema.presence === 'defaulted' && isJsonSerializable(schema.defaultValue)) {
|
|
598
|
+
result.default = schema.defaultValue;
|
|
599
|
+
}
|
|
600
|
+
if (schema.deprecated !== undefined) {
|
|
601
|
+
result.deprecated = true;
|
|
602
|
+
}
|
|
603
|
+
|
|
604
|
+
return result;
|
|
605
|
+
}
|
|
606
|
+
|
|
607
|
+
// --- Type mapping — args → JSON Schema types
|
|
608
|
+
|
|
609
|
+
function argToJsonSchemaType(schema: ArgSchema): Record<string, unknown> {
|
|
610
|
+
const kind = argKindToType(schema);
|
|
611
|
+
const result: Record<string, unknown> = schema.variadic
|
|
612
|
+
? { type: 'array', items: kind }
|
|
613
|
+
: { ...kind };
|
|
614
|
+
|
|
615
|
+
if (schema.description !== undefined) {
|
|
616
|
+
result.description = schema.description;
|
|
617
|
+
}
|
|
618
|
+
if (schema.presence === 'defaulted' && isJsonSerializable(schema.defaultValue)) {
|
|
619
|
+
result.default = schema.defaultValue;
|
|
620
|
+
}
|
|
621
|
+
if (schema.deprecated !== undefined) {
|
|
622
|
+
result.deprecated = true;
|
|
623
|
+
}
|
|
624
|
+
|
|
625
|
+
return result;
|
|
626
|
+
}
|
|
627
|
+
|
|
628
|
+
/** Map an arg's kind to a JSON Schema type fragment. */
|
|
629
|
+
function argKindToType(schema: ArgSchema): Record<string, unknown> {
|
|
630
|
+
switch (schema.kind) {
|
|
631
|
+
case 'string':
|
|
632
|
+
return { type: 'string' };
|
|
633
|
+
case 'number':
|
|
634
|
+
return { type: 'number' };
|
|
635
|
+
case 'enum': {
|
|
636
|
+
const result: Record<string, unknown> = { type: 'string' };
|
|
637
|
+
if (schema.enumValues !== undefined) {
|
|
638
|
+
result.enum = [...schema.enumValues];
|
|
639
|
+
}
|
|
640
|
+
return result;
|
|
641
|
+
}
|
|
642
|
+
case 'custom':
|
|
643
|
+
return {};
|
|
644
|
+
}
|
|
645
|
+
}
|
|
646
|
+
|
|
647
|
+
// === Utilities
|
|
648
|
+
|
|
649
|
+
/**
|
|
650
|
+
* Check whether a value can survive a JSON round-trip.
|
|
651
|
+
*
|
|
652
|
+
* Returns `false` for functions, symbols, bigints, non-finite numbers, and
|
|
653
|
+
* objects containing them. Used to guard default-value inclusion in
|
|
654
|
+
* serialized output.
|
|
655
|
+
*/
|
|
656
|
+
function isJsonSerializable(
|
|
657
|
+
value: unknown,
|
|
658
|
+
seen: WeakSet<object> = new WeakSet<object>(),
|
|
659
|
+
): boolean {
|
|
660
|
+
if (value === undefined) return false;
|
|
661
|
+
if (value === null) return true;
|
|
662
|
+
const t = typeof value;
|
|
663
|
+
if (t === 'string' || t === 'boolean') return true;
|
|
664
|
+
if (t === 'number') return Number.isFinite(value);
|
|
665
|
+
if (t === 'function' || t === 'symbol' || t === 'bigint') return false;
|
|
666
|
+
if (Array.isArray(value)) {
|
|
667
|
+
if (seen.has(value)) return false;
|
|
668
|
+
seen.add(value);
|
|
669
|
+
try {
|
|
670
|
+
return value.every((entry) => isJsonSerializable(entry, seen));
|
|
671
|
+
} finally {
|
|
672
|
+
seen.delete(value);
|
|
673
|
+
}
|
|
674
|
+
}
|
|
675
|
+
if (t === 'object') {
|
|
676
|
+
const objectValue = value as Record<string, unknown>;
|
|
677
|
+
if (!isPlainJsonObject(objectValue)) return false;
|
|
678
|
+
if (seen.has(objectValue)) return false;
|
|
679
|
+
seen.add(objectValue);
|
|
680
|
+
try {
|
|
681
|
+
return Object.values(objectValue).every((entry) => isJsonSerializable(entry, seen));
|
|
682
|
+
} finally {
|
|
683
|
+
seen.delete(objectValue);
|
|
684
|
+
}
|
|
685
|
+
}
|
|
686
|
+
return false;
|
|
687
|
+
}
|
|
688
|
+
|
|
689
|
+
/**
|
|
690
|
+
* Check whether an object is a plain JSON object.
|
|
691
|
+
*
|
|
692
|
+
* Accepts objects with `Object.prototype` or a null prototype, which are the
|
|
693
|
+
* only object shapes that round-trip through JSON as structural objects.
|
|
694
|
+
*
|
|
695
|
+
* @internal
|
|
696
|
+
*/
|
|
697
|
+
function isPlainJsonObject(value: object): value is Record<string, unknown> {
|
|
698
|
+
const proto = Object.getPrototypeOf(value);
|
|
699
|
+
return proto === Object.prototype || proto === null;
|
|
700
|
+
}
|
|
701
|
+
|
|
702
|
+
// === Exports
|
|
703
|
+
|
|
704
|
+
export type { JsonSchemaOptions };
|
|
705
|
+
export { generateInputSchema, generateSchema };
|