@kjanat/dreamcli 4.0.0-rc.3 → 4.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/README.md +5 -7
- package/dist/{runtime/adapter.d.mts → adapter-D0hbBNVB.d.mts} +2 -4
- package/dist/completion-D4mz6axB.mjs +6 -0
- package/dist/completion.d.mts +90 -0
- package/dist/completion.mjs +1 -0
- package/dist/config-B9ddC-Kb.mjs +1 -0
- package/dist/config.d.mts +2 -0
- package/dist/config.mjs +1 -0
- package/dist/core-Cp2w8vRq.mjs +17 -0
- package/dist/index-BziI2aKc.d.mts +5440 -0
- package/dist/index-DOfClfYR.d.mts +370 -0
- package/dist/index-DWsnGZlx.d.mts +831 -0
- package/dist/{core/cli/index.d.mts → index-DXROeDPC.d.mts} +116 -57
- package/dist/index-DndPmT8J.d.mts +275 -0
- package/dist/{core/json-schema/index.d.mts → index-DyoaS234.d.mts} +43 -34
- package/dist/index.d.mts +190 -41
- package/dist/index.mjs +1 -26
- package/dist/json-schema-C9SzZ7jY.mjs +52 -0
- package/dist/json-schema.d.mts +2 -0
- package/dist/json-schema.mjs +1 -0
- package/dist/package-json-BgE9YjjQ.mjs +3 -0
- package/dist/prompt.d.mts +48 -0
- package/dist/prompt.mjs +1 -0
- package/dist/rolldown-runtime-G4Kt5YOX.mjs +1 -0
- package/dist/runtime.d.mts +2 -6
- package/dist/runtime.mjs +1 -6
- package/dist/terminal-C8KTXjv5.mjs +6 -0
- package/dist/test-prompter-v__jT2yG.mjs +1 -0
- package/dist/testkit.d.mts +54 -6
- package/dist/testkit.mjs +1 -5
- package/dist/version.mjs +1 -7
- package/dreamcli.schema.json +697 -538
- package/package.json +29 -7
- package/skills/cli-creation/SKILL.md +16 -11
- package/CHANGELOG.md +0 -1116
- package/dist/core/cli/builtins.d.mts +0 -117
- package/dist/core/cli/builtins.mjs +0 -135
- package/dist/core/cli/compiled.d.mts +0 -66
- package/dist/core/cli/compiled.mjs +0 -76
- package/dist/core/cli/dispatch.d.mts +0 -115
- package/dist/core/cli/dispatch.mjs +0 -205
- package/dist/core/cli/help-links.d.mts +0 -27
- package/dist/core/cli/help-links.mjs +0 -41
- package/dist/core/cli/index.mjs +0 -1271
- package/dist/core/cli/planner.d.mts +0 -174
- package/dist/core/cli/planner.mjs +0 -323
- package/dist/core/cli/plugin.d.mts +0 -94
- package/dist/core/cli/plugin.mjs +0 -41
- package/dist/core/cli/propagate.d.mts +0 -39
- package/dist/core/cli/propagate.mjs +0 -57
- package/dist/core/cli/reserved-flags.d.mts +0 -19
- package/dist/core/cli/reserved-flags.mjs +0 -158
- package/dist/core/cli/root-help.d.mts +0 -53
- package/dist/core/cli/root-help.mjs +0 -221
- package/dist/core/cli/root-output-flags.d.mts +0 -74
- package/dist/core/cli/root-output-flags.mjs +0 -169
- package/dist/core/cli/root-surface.d.mts +0 -64
- package/dist/core/cli/root-surface.mjs +0 -28
- package/dist/core/cli/runtime-preflight.d.mts +0 -213
- package/dist/core/cli/runtime-preflight.mjs +0 -221
- package/dist/core/completion/index.d.mts +0 -76
- package/dist/core/completion/index.mjs +0 -90
- package/dist/core/completion/shells/bash.d.mts +0 -23
- package/dist/core/completion/shells/bash.mjs +0 -312
- package/dist/core/completion/shells/fish.d.mts +0 -19
- package/dist/core/completion/shells/fish.mjs +0 -164
- package/dist/core/completion/shells/powershell.d.mts +0 -13
- package/dist/core/completion/shells/powershell.mjs +0 -360
- package/dist/core/completion/shells/shared.d.mts +0 -164
- package/dist/core/completion/shells/shared.mjs +0 -147
- package/dist/core/completion/shells/zsh.d.mts +0 -23
- package/dist/core/completion/shells/zsh.mjs +0 -256
- package/dist/core/config/index.d.mts +0 -191
- package/dist/core/config/index.mjs +0 -285
- package/dist/core/config/package-json.d.mts +0 -179
- package/dist/core/config/package-json.mjs +0 -353
- package/dist/core/errors/index.d.mts +0 -125
- package/dist/core/errors/index.mjs +0 -87
- package/dist/core/execution/index.d.mts +0 -61
- package/dist/core/execution/index.mjs +0 -220
- package/dist/core/help/ansi.d.mts +0 -84
- package/dist/core/help/ansi.mjs +0 -121
- package/dist/core/help/index.d.mts +0 -149
- package/dist/core/help/index.mjs +0 -418
- package/dist/core/help/theme.d.mts +0 -86
- package/dist/core/help/theme.mjs +0 -69
- package/dist/core/json-schema/index.mjs +0 -1008
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +0 -274
- package/dist/core/json-schema/meta-descriptions.generated.mjs +0 -136
- package/dist/core/output/activity.d.mts +0 -193
- package/dist/core/output/activity.mjs +0 -452
- package/dist/core/output/bind.d.mts +0 -37
- package/dist/core/output/bind.mjs +0 -56
- package/dist/core/output/contracts.d.mts +0 -82
- package/dist/core/output/contracts.mjs +0 -57
- package/dist/core/output/display-value.d.mts +0 -19
- package/dist/core/output/display-value.mjs +0 -32
- package/dist/core/output/index.d.mts +0 -344
- package/dist/core/output/index.mjs +0 -514
- package/dist/core/output/renderers.d.mts +0 -45
- package/dist/core/output/renderers.mjs +0 -46
- package/dist/core/output/writer.d.mts +0 -39
- package/dist/core/output/writer.mjs +0 -12
- package/dist/core/parse/index.d.mts +0 -178
- package/dist/core/parse/index.mjs +0 -850
- package/dist/core/parse/occurrences.d.mts +0 -90
- package/dist/core/parse/occurrences.mjs +0 -114
- package/dist/core/prompt/index.d.mts +0 -213
- package/dist/core/prompt/index.mjs +0 -348
- package/dist/core/read-flags/index.d.mts +0 -150
- package/dist/core/read-flags/index.mjs +0 -217
- package/dist/core/resolve/args.d.mts +0 -39
- package/dist/core/resolve/args.mjs +0 -182
- package/dist/core/resolve/coerce.d.mts +0 -79
- package/dist/core/resolve/coerce.mjs +0 -900
- package/dist/core/resolve/config.d.mts +0 -10
- package/dist/core/resolve/config.mjs +0 -19
- package/dist/core/resolve/contracts.d.mts +0 -146
- package/dist/core/resolve/errors.d.mts +0 -10
- package/dist/core/resolve/errors.mjs +0 -148
- package/dist/core/resolve/flags.d.mts +0 -74
- package/dist/core/resolve/flags.mjs +0 -246
- package/dist/core/resolve/index.d.mts +0 -44
- package/dist/core/resolve/index.mjs +0 -123
- package/dist/core/resolve/path-checks.d.mts +0 -48
- package/dist/core/resolve/path-checks.mjs +0 -102
- package/dist/core/resolve/redaction.d.mts +0 -13
- package/dist/core/resolve/redaction.mjs +0 -14
- package/dist/core/resolve/stages.d.mts +0 -86
- package/dist/core/resolve/stages.mjs +0 -170
- package/dist/core/resolve/standard.d.mts +0 -26
- package/dist/core/resolve/standard.mjs +0 -212
- package/dist/core/schema/activity.d.mts +0 -189
- package/dist/core/schema/arg.d.mts +0 -1461
- package/dist/core/schema/arg.mjs +0 -1139
- package/dist/core/schema/brand.d.mts +0 -17
- package/dist/core/schema/cardinality.d.mts +0 -302
- package/dist/core/schema/cardinality.mjs +0 -514
- package/dist/core/schema/command.d.mts +0 -1132
- package/dist/core/schema/command.mjs +0 -999
- package/dist/core/schema/flag.d.mts +0 -1495
- package/dist/core/schema/flag.mjs +0 -1207
- package/dist/core/schema/index.d.mts +0 -15
- package/dist/core/schema/index.mjs +0 -10
- package/dist/core/schema/middleware.d.mts +0 -129
- package/dist/core/schema/middleware.mjs +0 -41
- package/dist/core/schema/number-constraints.d.mts +0 -96
- package/dist/core/schema/number-constraints.mjs +0 -60
- package/dist/core/schema/prompt.d.mts +0 -135
- package/dist/core/schema/provenance.d.mts +0 -99
- package/dist/core/schema/provenance.mjs +0 -28
- package/dist/core/schema/run.d.mts +0 -211
- package/dist/core/schema/source.d.mts +0 -180
- package/dist/core/schema/source.mjs +0 -206
- package/dist/core/schema/standard.d.mts +0 -100
- package/dist/core/schema/standard.mjs +0 -15
- package/dist/core/schema/stdin.d.mts +0 -97
- package/dist/core/schema/stdin.mjs +0 -91
- package/dist/core/schema/string-constraints.d.mts +0 -108
- package/dist/core/schema/string-constraints.mjs +0 -86
- package/dist/core/schema/value-parsers.d.mts +0 -150
- package/dist/core/schema/value-parsers.mjs +0 -160
- package/dist/core/schema/value.d.mts +0 -243
- package/dist/core/schema/value.mjs +0 -573
- package/dist/core/testkit/index.d.mts +0 -63
- package/dist/core/testkit/index.mjs +0 -102
- package/dist/runtime/adapter.mjs +0 -92
- package/dist/runtime/auto.d.mts +0 -25
- package/dist/runtime/auto.mjs +0 -45
- package/dist/runtime/deno.d.mts +0 -99
- package/dist/runtime/deno.mjs +0 -265
- package/dist/runtime/detect.d.mts +0 -86
- package/dist/runtime/detect.mjs +0 -45
- package/dist/runtime/index.d.mts +0 -6
- package/dist/runtime/node.d.mts +0 -71
- package/dist/runtime/node.mjs +0 -228
- package/dist/runtime/paths.d.mts +0 -31
- package/dist/runtime/paths.mjs +0 -48
- package/dist/strings.d.mts +0 -27
- package/dist/strings.mjs +0 -22
- package/examples/basic.ts +0 -37
- package/examples/flag-types.ts +0 -79
- package/examples/gh/package.json +0 -45
- package/examples/gh/src/commands/auth.ts +0 -66
- package/examples/gh/src/commands/issue.ts +0 -120
- package/examples/gh/src/commands/pr.ts +0 -125
- package/examples/gh/src/data/issues.yaml +0 -5
- package/examples/gh/src/data/issues.yaml.d.ts +0 -17
- package/examples/gh/src/data/pull-requests.yaml +0 -7
- package/examples/gh/src/data/pull-requests.yaml.d.ts +0 -18
- package/examples/gh/src/docs.ts +0 -11
- package/examples/gh/src/lib/auth.ts +0 -37
- package/examples/gh/src/lib/utils.ts +0 -17
- package/examples/gh/src/main.test.ts +0 -307
- package/examples/gh/src/main.ts +0 -46
- package/examples/help-config.ts +0 -43
- package/examples/interactive.ts +0 -67
- package/examples/json-mode.ts +0 -95
- package/examples/middleware.ts +0 -71
- package/examples/multi-command.ts +0 -66
- package/examples/output-extras.ts +0 -46
- package/examples/parser-control.ts +0 -40
- package/examples/pwsh-demo/README.md +0 -40
- package/examples/pwsh-demo/package.json +0 -41
- package/examples/pwsh-demo/pwsh-demo.cmd +0 -3
- package/examples/pwsh-demo/smoke-powershell.ps1 +0 -218
- package/examples/pwsh-demo/src/main.test.ts +0 -45
- package/examples/pwsh-demo/src/main.ts +0 -140
- package/examples/spinner-progress.ts +0 -49
- package/examples/standard-schema.ts +0 -45
- package/examples/testing.ts +0 -147
- package/examples/transport-launcher.ts +0 -85
|
@@ -1,1008 +0,0 @@
|
|
|
1
|
-
import { DUPLICATE_KEYS } from "../schema/cardinality.mjs";
|
|
2
|
-
import { getFlagAliasNames } from "../schema/flag.mjs";
|
|
3
|
-
import { resolveExampleCommand } from "../schema/command.mjs";
|
|
4
|
-
import { resolvePlainHelpDescription } from "../help/theme.mjs";
|
|
5
|
-
import { definitionMetaSchemaDescriptions } from "./meta-descriptions.generated.mjs";
|
|
6
|
-
//#region src/core/json-schema/index.ts
|
|
7
|
-
/**
|
|
8
|
-
* Apply defaults to optional {@link JsonSchemaOptions}.
|
|
9
|
-
*
|
|
10
|
-
* @param options - User-supplied schema generation options, or `undefined` for all defaults.
|
|
11
|
-
* @returns Fully resolved options with defaults applied.
|
|
12
|
-
*/
|
|
13
|
-
function resolveOptions(options) {
|
|
14
|
-
return {
|
|
15
|
-
includeHidden: options?.includeHidden ?? true,
|
|
16
|
-
includePrompts: options?.includePrompts ?? true
|
|
17
|
-
};
|
|
18
|
-
}
|
|
19
|
-
/**
|
|
20
|
-
* `$schema` URL for definition documents.
|
|
21
|
-
*
|
|
22
|
-
* Self-hosted. The `v1` segment is the definition format version, the value
|
|
23
|
-
* every document reports as `schemaVersion`, so it resolves for every package
|
|
24
|
-
* release that emits `schemaVersion: 1`. Two mirrors carry identical bytes:
|
|
25
|
-
* `./node_modules/@kjanat/dreamcli/dreamcli.schema.json` for offline or
|
|
26
|
-
* local-first workflows, and
|
|
27
|
-
* `https://cdn.jsdelivr.net/npm/@kjanat/dreamcli/dreamcli.schema.json` on the
|
|
28
|
-
* npm CDN.
|
|
29
|
-
*/
|
|
30
|
-
const DEFINITION_SCHEMA_URL = "https://dreamcli.kjanat.dev/schemas/definition/v1.schema.json";
|
|
31
|
-
/** Meta-schema URL for JSON Schema draft 2020-12 (input validation). */
|
|
32
|
-
const JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
|
|
33
|
-
/**
|
|
34
|
-
* Version of the definition document format emitted by {@link generateSchema}
|
|
35
|
-
* and {@link generateCommandSchema}.
|
|
36
|
-
*/
|
|
37
|
-
const DEFINITION_SCHEMA_VERSION = 1;
|
|
38
|
-
/**
|
|
39
|
-
* Generate a definition metadata document describing the CLI's structure.
|
|
40
|
-
*
|
|
41
|
-
* Walks the full command tree and produces a plain JSON-serializable object
|
|
42
|
-
* representing all commands, subcommands, flags, args, and metadata.
|
|
43
|
-
* Non-serializable runtime values (parse functions, interactive resolvers)
|
|
44
|
-
* are omitted.
|
|
45
|
-
*
|
|
46
|
-
* @param schema - The CLI schema from `CLIBuilder.schema`.
|
|
47
|
-
* @param options - Generation options.
|
|
48
|
-
* @param meta - Program name/version for function-form examples; defaults to
|
|
49
|
-
* the CLI schema's own `name`/`version`.
|
|
50
|
-
* @returns A plain object suitable for `JSON.stringify()`.
|
|
51
|
-
*
|
|
52
|
-
* @example
|
|
53
|
-
* ```ts
|
|
54
|
-
* const app = cli('myapp').version('1.0.0').command(deploy);
|
|
55
|
-
* const definition = generateSchema(app.schema);
|
|
56
|
-
* writeFileSync('cli-schema.json', JSON.stringify(definition, null, 2));
|
|
57
|
-
* ```
|
|
58
|
-
*/
|
|
59
|
-
function generateSchema(schema, options, meta) {
|
|
60
|
-
const opts = resolveOptions(options);
|
|
61
|
-
const resolvedMeta = meta ?? {
|
|
62
|
-
name: schema.name,
|
|
63
|
-
version: schema.version
|
|
64
|
-
};
|
|
65
|
-
const defaultCommand = schema.defaultCommand !== void 0 && (opts.includeHidden || !schema.defaultCommand.hidden) ? serializeCommand(schema.defaultCommand, opts, resolvedMeta) : void 0;
|
|
66
|
-
return {
|
|
67
|
-
$schema: DEFINITION_SCHEMA_URL,
|
|
68
|
-
schemaVersion: 1,
|
|
69
|
-
name: schema.name,
|
|
70
|
-
...schema.version !== void 0 ? { version: schema.version } : {},
|
|
71
|
-
...schema.description !== void 0 ? { description: resolvePlainHelpDescription(schema.description) } : {},
|
|
72
|
-
...defaultCommand !== void 0 ? { defaultCommand } : {},
|
|
73
|
-
commands: schema.commands.filter((cmd) => opts.includeHidden || !cmd.hidden).map((cmd) => serializeCommand(cmd, opts, resolvedMeta))
|
|
74
|
-
};
|
|
75
|
-
}
|
|
76
|
-
/**
|
|
77
|
-
* Generate the definition metadata document for a single command.
|
|
78
|
-
*
|
|
79
|
-
* The per-command counterpart of {@link generateSchema}: one entry of its
|
|
80
|
-
* `commands` array (flags, args, subcommands, examples), plus the
|
|
81
|
-
* `schemaVersion` every standalone document carries. Powers `--help` in
|
|
82
|
-
* `--json` mode and is useful for embedding one command's definition into
|
|
83
|
-
* custom tooling.
|
|
84
|
-
*
|
|
85
|
-
* @param schema - The command schema to serialize.
|
|
86
|
-
* @param options - Generation options.
|
|
87
|
-
* @param meta - Program name/version for function-form examples; defaults to
|
|
88
|
-
* the command's own name with no version.
|
|
89
|
-
* @returns A plain object suitable for `JSON.stringify()`.
|
|
90
|
-
* @remarks Validate standalone output against
|
|
91
|
-
* `https://dreamcli.kjanat.dev/schemas/definition/v1.schema.json#/$defs/commandDocument`.
|
|
92
|
-
*/
|
|
93
|
-
function generateCommandSchema(schema, options, meta) {
|
|
94
|
-
const resolvedMeta = meta ?? {
|
|
95
|
-
name: schema.name,
|
|
96
|
-
version: void 0
|
|
97
|
-
};
|
|
98
|
-
return {
|
|
99
|
-
schemaVersion: 1,
|
|
100
|
-
...serializeCommand(schema, resolveOptions(options), resolvedMeta)
|
|
101
|
-
};
|
|
102
|
-
}
|
|
103
|
-
/**
|
|
104
|
-
* Serialize a single {@link CommandSchema} into a plain object.
|
|
105
|
-
*
|
|
106
|
-
* @param schema - The command schema to serialize.
|
|
107
|
-
* @param opts - Resolved generation options (hidden/prompt inclusion).
|
|
108
|
-
* @returns JSON-serializable object representing the command.
|
|
109
|
-
*/
|
|
110
|
-
function serializeCommand(schema, opts, meta) {
|
|
111
|
-
const flags = {};
|
|
112
|
-
for (const [name, flagDef] of Object.entries(schema.flags)) flags[name] = serializeFlag(flagDef, opts);
|
|
113
|
-
return {
|
|
114
|
-
name: schema.name,
|
|
115
|
-
...schema.description !== void 0 ? { description: resolvePlainHelpDescription(schema.description) } : {},
|
|
116
|
-
...schema.aliases.length > 0 ? { aliases: [...schema.aliases] } : {},
|
|
117
|
-
...schema.hidden ? { hidden: true } : {},
|
|
118
|
-
...schema.examples.length > 0 ? { examples: schema.examples.map((example) => serializeExample(example, meta)) } : {},
|
|
119
|
-
flags,
|
|
120
|
-
args: schema.args.map((entry) => serializeArgEntry(entry, opts)),
|
|
121
|
-
commands: schema.commands.filter((cmd) => opts.includeHidden || !cmd.hidden).map((cmd) => serializeCommand(cmd, opts, meta))
|
|
122
|
-
};
|
|
123
|
-
}
|
|
124
|
-
/**
|
|
125
|
-
* Serialize a {@link FlagSchema} into a plain object.
|
|
126
|
-
*
|
|
127
|
-
* @param schema - The flag schema to serialize.
|
|
128
|
-
* @param opts - Resolved generation options (prompt inclusion).
|
|
129
|
-
* @returns JSON-serializable object representing the flag.
|
|
130
|
-
*/
|
|
131
|
-
function serializeFlag(schema, opts) {
|
|
132
|
-
const visibleAliases = getFlagAliasNames(schema);
|
|
133
|
-
const stringConstraints = schema.stringConstraints;
|
|
134
|
-
const pathChecks = schema.pathChecks;
|
|
135
|
-
const negation = schema.negation;
|
|
136
|
-
return {
|
|
137
|
-
kind: schema.kind,
|
|
138
|
-
presence: schema.presence,
|
|
139
|
-
...isJsonSerializable(schema.defaultValue) ? { defaultValue: schema.defaultValue } : {},
|
|
140
|
-
...visibleAliases.length > 0 ? { aliases: [...visibleAliases] } : {},
|
|
141
|
-
...schema.stdin !== void 0 ? { stdin: serializeStdin(schema.stdin) } : {},
|
|
142
|
-
...schema.envVar !== void 0 ? { envVar: schema.envVar } : {},
|
|
143
|
-
...schema.configPath !== void 0 ? { configPath: schema.configPath } : {},
|
|
144
|
-
...schema.description !== void 0 ? { description: resolvePlainHelpDescription(schema.description) } : {},
|
|
145
|
-
...schema.enumValues !== void 0 ? { enumValues: [...schema.enumValues] } : {},
|
|
146
|
-
...schema.numberConstraints !== void 0 ? { numberConstraints: { ...schema.numberConstraints } } : {},
|
|
147
|
-
...stringConstraints !== void 0 ? { stringConstraints: serializeStringConstraints(stringConstraints) } : {},
|
|
148
|
-
...schema.elementSchema !== void 0 ? { elementSchema: serializeFlag(schema.elementSchema, opts) } : {},
|
|
149
|
-
...schema.separator !== void 0 ? { separator: schema.separator } : {},
|
|
150
|
-
...schema.split !== void 0 ? { split: serializeSplit(schema.split) } : {},
|
|
151
|
-
...schema.duplicateKeys !== "last" ? { duplicateKeys: schema.duplicateKeys } : {},
|
|
152
|
-
...schema.unique ? { unique: true } : {},
|
|
153
|
-
...pathChecks !== void 0 ? { pathChecks: serializePathChecks(pathChecks) } : {},
|
|
154
|
-
...schema.valueHint !== void 0 ? { valueHint: schema.valueHint } : {},
|
|
155
|
-
...opts.includePrompts && schema.prompt !== void 0 ? { prompt: serializePrompt(schema.prompt) } : {},
|
|
156
|
-
...schema.deprecated !== void 0 ? { deprecated: schema.deprecated } : {},
|
|
157
|
-
...schema.propagate ? { propagate: true } : {},
|
|
158
|
-
...negation !== void 0 ? { negation: {
|
|
159
|
-
...negation.alias !== void 0 ? { alias: negation.alias } : {},
|
|
160
|
-
...negation.hidden ? { hidden: true } : {}
|
|
161
|
-
} } : {},
|
|
162
|
-
...schema.duplicates !== "last" ? { duplicates: schema.duplicates } : {}
|
|
163
|
-
};
|
|
164
|
-
}
|
|
165
|
-
/**
|
|
166
|
-
* Serialize {@link StringConstraints} into a plain object.
|
|
167
|
-
*
|
|
168
|
-
* @param constraints - The string constraints to serialize.
|
|
169
|
-
* @returns JSON-serializable object with the pattern split into source and flags.
|
|
170
|
-
*/
|
|
171
|
-
function serializeStringConstraints(constraints) {
|
|
172
|
-
const pattern = constraints.pattern;
|
|
173
|
-
return {
|
|
174
|
-
...constraints.nonEmpty !== void 0 ? { nonEmpty: constraints.nonEmpty } : {},
|
|
175
|
-
...constraints.minLength !== void 0 ? { minLength: constraints.minLength } : {},
|
|
176
|
-
...constraints.maxLength !== void 0 ? { maxLength: constraints.maxLength } : {},
|
|
177
|
-
...pattern !== void 0 ? { pattern: {
|
|
178
|
-
source: pattern.source,
|
|
179
|
-
flags: pattern.flags
|
|
180
|
-
} } : {}
|
|
181
|
-
};
|
|
182
|
-
}
|
|
183
|
-
/**
|
|
184
|
-
* Serialize {@link PathChecks} into a plain object.
|
|
185
|
-
*
|
|
186
|
-
* @param checks - The filesystem expectations to serialize.
|
|
187
|
-
* @returns JSON-serializable object omitting the defaults.
|
|
188
|
-
* @internal
|
|
189
|
-
*/
|
|
190
|
-
function serializePathChecks(checks) {
|
|
191
|
-
return {
|
|
192
|
-
mustExist: checks.mustExist,
|
|
193
|
-
...checks.type !== void 0 ? { type: checks.type } : {},
|
|
194
|
-
...checks.create ? { create: true } : {}
|
|
195
|
-
};
|
|
196
|
-
}
|
|
197
|
-
/**
|
|
198
|
-
* Serialize a {@link CommandArgEntry} into a plain object.
|
|
199
|
-
*
|
|
200
|
-
* @param entry - The positional arg entry (name + {@link ArgSchema}).
|
|
201
|
-
* @param opts - Resolved generation options (prompt inclusion).
|
|
202
|
-
* @returns JSON-serializable object representing the arg.
|
|
203
|
-
*/
|
|
204
|
-
function serializeArgEntry(entry, opts) {
|
|
205
|
-
return {
|
|
206
|
-
name: entry.name,
|
|
207
|
-
...serializeArgValue(entry.schema, opts)
|
|
208
|
-
};
|
|
209
|
-
}
|
|
210
|
-
/**
|
|
211
|
-
* Serialize the value half of an {@link ArgSchema} into a plain object.
|
|
212
|
-
*
|
|
213
|
-
* @param schema - The arg schema to serialize.
|
|
214
|
-
* @param opts - Resolved generation options (prompt inclusion).
|
|
215
|
-
* @returns JSON-serializable object representing everything but the name.
|
|
216
|
-
*/
|
|
217
|
-
function serializeArgValue(schema, opts) {
|
|
218
|
-
const stringConstraints = schema.stringConstraints;
|
|
219
|
-
const pathChecks = schema.pathChecks;
|
|
220
|
-
return {
|
|
221
|
-
kind: schema.kind,
|
|
222
|
-
presence: schema.presence,
|
|
223
|
-
...schema.variadic ? { variadic: true } : {},
|
|
224
|
-
...schema.stdin !== void 0 ? { stdin: serializeStdin(schema.stdin) } : {},
|
|
225
|
-
...isJsonSerializable(schema.defaultValue) ? { defaultValue: schema.defaultValue } : {},
|
|
226
|
-
...schema.description !== void 0 ? { description: resolvePlainHelpDescription(schema.description) } : {},
|
|
227
|
-
...schema.envVar !== void 0 ? { envVar: schema.envVar } : {},
|
|
228
|
-
...schema.configPath !== void 0 ? { configPath: schema.configPath } : {},
|
|
229
|
-
...schema.enumValues !== void 0 ? { enumValues: [...schema.enumValues] } : {},
|
|
230
|
-
...schema.elementSchema !== void 0 ? { elementSchema: serializeArgElementValue(schema.elementSchema) } : {},
|
|
231
|
-
...schema.numberConstraints !== void 0 ? { numberConstraints: { ...schema.numberConstraints } } : {},
|
|
232
|
-
...stringConstraints !== void 0 ? { stringConstraints: serializeStringConstraints(stringConstraints) } : {},
|
|
233
|
-
...pathChecks !== void 0 ? { pathChecks: serializePathChecks(pathChecks) } : {},
|
|
234
|
-
...schema.valueHint !== void 0 ? { valueHint: schema.valueHint } : {},
|
|
235
|
-
...schema.separator !== void 0 ? { separator: schema.separator } : {},
|
|
236
|
-
...schema.split !== void 0 ? { split: serializeSplit(schema.split) } : {},
|
|
237
|
-
...schema.duplicateKeys !== "last" ? { duplicateKeys: schema.duplicateKeys } : {},
|
|
238
|
-
...schema.unique ? { unique: true } : {},
|
|
239
|
-
...opts.includePrompts && schema.prompt !== void 0 ? { prompt: serializePrompt(schema.prompt) } : {},
|
|
240
|
-
...schema.deprecated !== void 0 ? { deprecated: schema.deprecated } : {}
|
|
241
|
-
};
|
|
242
|
-
}
|
|
243
|
-
/** Serialize only the value-axis fields an entry element supports. */
|
|
244
|
-
function serializeArgElementValue(schema) {
|
|
245
|
-
if (schema.kind === "keyValue") throw new TypeError("Arg element schema kind 'keyValue' is not supported");
|
|
246
|
-
return {
|
|
247
|
-
kind: schema.kind,
|
|
248
|
-
presence: "required",
|
|
249
|
-
...schema.enumValues !== void 0 ? { enumValues: [...schema.enumValues] } : {},
|
|
250
|
-
...schema.numberConstraints !== void 0 ? { numberConstraints: { ...schema.numberConstraints } } : {},
|
|
251
|
-
...schema.stringConstraints !== void 0 ? { stringConstraints: serializeStringConstraints(schema.stringConstraints) } : {},
|
|
252
|
-
...schema.pathChecks !== void 0 ? { pathChecks: serializePathChecks(schema.pathChecks) } : {},
|
|
253
|
-
...schema.valueHint !== void 0 ? { valueHint: schema.valueHint } : {}
|
|
254
|
-
};
|
|
255
|
-
}
|
|
256
|
-
/**
|
|
257
|
-
* Serialize the non-CLI split policies of a collection.
|
|
258
|
-
*
|
|
259
|
-
* @param split - The stored split binding.
|
|
260
|
-
* @returns JSON-serializable object naming only the sources it sets.
|
|
261
|
-
*/
|
|
262
|
-
function serializeSplit(split) {
|
|
263
|
-
return {
|
|
264
|
-
...split.env !== void 0 ? { env: { ...split.env } } : {},
|
|
265
|
-
...split.stdin !== void 0 ? { stdin: { ...split.stdin } } : {}
|
|
266
|
-
};
|
|
267
|
-
}
|
|
268
|
-
/**
|
|
269
|
-
* Serialize a {@link StdinBinding} into a plain object.
|
|
270
|
-
*
|
|
271
|
-
* @param stdin - The stdin axis to serialize.
|
|
272
|
-
* @returns JSON-serializable object naming the trigger, the sharing mode, and
|
|
273
|
-
* the trimming.
|
|
274
|
-
*/
|
|
275
|
-
function serializeStdin(stdin) {
|
|
276
|
-
return {
|
|
277
|
-
when: stdin.when,
|
|
278
|
-
consume: stdin.consume,
|
|
279
|
-
trim: stdin.trim
|
|
280
|
-
};
|
|
281
|
-
}
|
|
282
|
-
/**
|
|
283
|
-
* Serialize a {@link PromptConfig} into a plain object.
|
|
284
|
-
*
|
|
285
|
-
* @param prompt - The prompt configuration to serialize.
|
|
286
|
-
* @returns JSON-serializable object representing the prompt.
|
|
287
|
-
*/
|
|
288
|
-
function serializePrompt(prompt) {
|
|
289
|
-
switch (prompt.kind) {
|
|
290
|
-
case "input": return {
|
|
291
|
-
kind: prompt.kind,
|
|
292
|
-
message: prompt.message,
|
|
293
|
-
...prompt.placeholder !== void 0 ? { placeholder: prompt.placeholder } : {}
|
|
294
|
-
};
|
|
295
|
-
case "select": return {
|
|
296
|
-
kind: prompt.kind,
|
|
297
|
-
message: prompt.message,
|
|
298
|
-
...prompt.choices !== void 0 ? { choices: prompt.choices.map(serializeChoice) } : {}
|
|
299
|
-
};
|
|
300
|
-
case "multiselect": return {
|
|
301
|
-
kind: prompt.kind,
|
|
302
|
-
message: prompt.message,
|
|
303
|
-
...prompt.choices !== void 0 ? { choices: prompt.choices.map(serializeChoice) } : {},
|
|
304
|
-
...prompt.min !== void 0 ? { min: prompt.min } : {},
|
|
305
|
-
...prompt.max !== void 0 ? { max: prompt.max } : {}
|
|
306
|
-
};
|
|
307
|
-
case "confirm": return {
|
|
308
|
-
kind: prompt.kind,
|
|
309
|
-
message: prompt.message
|
|
310
|
-
};
|
|
311
|
-
}
|
|
312
|
-
}
|
|
313
|
-
/**
|
|
314
|
-
* Serialize a {@link SelectChoice} into a plain object.
|
|
315
|
-
*
|
|
316
|
-
* @param choice - The select/multiselect choice to serialize.
|
|
317
|
-
* @returns JSON-serializable object with value, optional label and description.
|
|
318
|
-
*/
|
|
319
|
-
function serializeChoice(choice) {
|
|
320
|
-
return {
|
|
321
|
-
value: choice.value,
|
|
322
|
-
...choice.label !== void 0 ? { label: choice.label } : {},
|
|
323
|
-
...choice.description !== void 0 ? { description: choice.description } : {}
|
|
324
|
-
};
|
|
325
|
-
}
|
|
326
|
-
/**
|
|
327
|
-
* Serialize a {@link CommandExample} into a plain object.
|
|
328
|
-
*
|
|
329
|
-
* Function-form commands are resolved against `meta` so the output is a plain
|
|
330
|
-
* serializable string rather than a dropped function.
|
|
331
|
-
*
|
|
332
|
-
* @param example - The example to serialize.
|
|
333
|
-
* @param meta - Program name/version passed to function-form commands.
|
|
334
|
-
* @returns JSON-serializable object with command and optional description.
|
|
335
|
-
*/
|
|
336
|
-
function serializeExample(example, meta) {
|
|
337
|
-
return {
|
|
338
|
-
command: resolveExampleCommand(example.command, meta),
|
|
339
|
-
...example.description !== void 0 ? { description: example.description } : {}
|
|
340
|
-
};
|
|
341
|
-
}
|
|
342
|
-
/**
|
|
343
|
-
* Generate a JSON Schema (draft 2020-12) for validating CLI input as JSON.
|
|
344
|
-
*
|
|
345
|
-
* Accepts either a full {@link CLISchema} (producing a discriminated union
|
|
346
|
-
* across all commands) or a single {@link CommandSchema} (producing a flat
|
|
347
|
-
* object schema for that command's flags and args).
|
|
348
|
-
*
|
|
349
|
-
* **Single command** — produces an object schema where flag/arg names are
|
|
350
|
-
* properties with appropriate JSON Schema types.
|
|
351
|
-
*
|
|
352
|
-
* **Multi-command CLI** — produces a `oneOf` discriminated union with a
|
|
353
|
-
* `command` property identifying each branch. Nested subcommands use
|
|
354
|
-
* dot-delimited paths (e.g. `"deploy.rollback"`).
|
|
355
|
-
*
|
|
356
|
-
* Only commands with action handlers are included (group commands without
|
|
357
|
-
* actions are not directly invocable and are skipped).
|
|
358
|
-
*
|
|
359
|
-
* @param schema - A CLI schema or a single command schema.
|
|
360
|
-
* @param options - Generation options.
|
|
361
|
-
* @returns A JSON Schema object suitable for `JSON.stringify()`.
|
|
362
|
-
*
|
|
363
|
-
* @example
|
|
364
|
-
* ```ts
|
|
365
|
-
* // Validate a config file against the CLI's input shape
|
|
366
|
-
* const inputSchema = generateInputSchema(app.schema);
|
|
367
|
-
* writeFileSync('input-schema.json', JSON.stringify(inputSchema, null, 2));
|
|
368
|
-
* ```
|
|
369
|
-
*/
|
|
370
|
-
function generateInputSchema(schema, options) {
|
|
371
|
-
const opts = resolveOptions(options);
|
|
372
|
-
if (isCommandSchema(schema)) return {
|
|
373
|
-
$schema: JSON_SCHEMA_DRAFT,
|
|
374
|
-
...commandToInputSchema(schema)
|
|
375
|
-
};
|
|
376
|
-
const branches = [];
|
|
377
|
-
if (schema.defaultCommand !== void 0 && (opts.includeHidden || !schema.defaultCommand.hidden)) collectInputBranches(schema.defaultCommand, "", branches, opts);
|
|
378
|
-
for (const cmd of schema.commands) {
|
|
379
|
-
if (cmd === schema.defaultCommand || cmd.name === schema.defaultCommand?.name) continue;
|
|
380
|
-
if (!opts.includeHidden && cmd.hidden) continue;
|
|
381
|
-
collectInputBranches(cmd, "", branches, opts);
|
|
382
|
-
}
|
|
383
|
-
const [onlyBranch] = branches;
|
|
384
|
-
if (branches.length === 1 && onlyBranch !== void 0) return {
|
|
385
|
-
$schema: JSON_SCHEMA_DRAFT,
|
|
386
|
-
...stripCommandDiscriminator(onlyBranch)
|
|
387
|
-
};
|
|
388
|
-
if (branches.length > 0) {
|
|
389
|
-
const defaultBranchName = schema.defaultCommand !== void 0 && (opts.includeHidden || !schema.defaultCommand.hidden) ? schema.defaultCommand.name : void 0;
|
|
390
|
-
const normalizedBranches = defaultBranchName !== void 0 ? branches.map((branch) => getBranchCommandDiscriminator(branch) === defaultBranchName ? stripCommandDiscriminator(branch) : branch) : branches;
|
|
391
|
-
return {
|
|
392
|
-
$schema: JSON_SCHEMA_DRAFT,
|
|
393
|
-
oneOf: normalizedBranches
|
|
394
|
-
};
|
|
395
|
-
}
|
|
396
|
-
return {
|
|
397
|
-
$schema: JSON_SCHEMA_DRAFT,
|
|
398
|
-
type: "object"
|
|
399
|
-
};
|
|
400
|
-
}
|
|
401
|
-
/**
|
|
402
|
-
* Discriminate between CLISchema and CommandSchema at runtime.
|
|
403
|
-
*
|
|
404
|
-
* Use a command-only field combination rather than a single shape check:
|
|
405
|
-
* command schemas always carry flags, args, and hasAction, while the CLI root
|
|
406
|
-
* schema does not expose that execution surface.
|
|
407
|
-
*/
|
|
408
|
-
function isCommandSchema(schema) {
|
|
409
|
-
return "flags" in schema && "args" in schema && "hasAction" in schema;
|
|
410
|
-
}
|
|
411
|
-
/** Recursively collect input schema branches for all invocable commands. */
|
|
412
|
-
function collectInputBranches(schema, prefix, branches, opts) {
|
|
413
|
-
const path = prefix ? `${prefix}.${schema.name}` : schema.name;
|
|
414
|
-
if (schema.hasAction) branches.push(commandToInputSchema(schema, path));
|
|
415
|
-
for (const sub of schema.commands) {
|
|
416
|
-
if (!opts.includeHidden && sub.hidden) continue;
|
|
417
|
-
collectInputBranches(sub, path, branches, opts);
|
|
418
|
-
}
|
|
419
|
-
}
|
|
420
|
-
/**
|
|
421
|
-
* Create a JSON Schema object for a single command's flags + args.
|
|
422
|
-
*
|
|
423
|
-
* When `commandPath` is provided, a `command` const discriminator property
|
|
424
|
-
* is added and required (used in multi-command oneOf schemas).
|
|
425
|
-
*/
|
|
426
|
-
function commandToInputSchema(schema, commandPath) {
|
|
427
|
-
const properties = {};
|
|
428
|
-
const required = [];
|
|
429
|
-
if (commandPath !== void 0) {
|
|
430
|
-
properties.command = { const: commandPath };
|
|
431
|
-
required.push("command");
|
|
432
|
-
}
|
|
433
|
-
for (const [name, flagDef] of Object.entries(schema.flags)) {
|
|
434
|
-
properties[name] = flagToJsonSchemaType(flagDef);
|
|
435
|
-
if (flagDef.presence === "required") required.push(name);
|
|
436
|
-
}
|
|
437
|
-
for (const entry of schema.args) {
|
|
438
|
-
properties[entry.name] = argToJsonSchemaType(entry.schema);
|
|
439
|
-
if (entry.schema.presence === "required") required.push(entry.name);
|
|
440
|
-
}
|
|
441
|
-
return {
|
|
442
|
-
type: "object",
|
|
443
|
-
properties,
|
|
444
|
-
additionalProperties: false,
|
|
445
|
-
...required.length > 0 ? { required } : {}
|
|
446
|
-
};
|
|
447
|
-
}
|
|
448
|
-
/** @internal */
|
|
449
|
-
function stripCommandDiscriminator(branch) {
|
|
450
|
-
const { command: _discriminator, ...properties } = branch.properties;
|
|
451
|
-
const required = branch.required?.filter((value) => value !== "command");
|
|
452
|
-
return {
|
|
453
|
-
type: branch.type,
|
|
454
|
-
properties,
|
|
455
|
-
additionalProperties: branch.additionalProperties,
|
|
456
|
-
...required !== void 0 && required.length > 0 ? { required } : {}
|
|
457
|
-
};
|
|
458
|
-
}
|
|
459
|
-
function getBranchCommandDiscriminator(branch) {
|
|
460
|
-
const commandValue = branch.properties.command;
|
|
461
|
-
if (commandValue === void 0) return;
|
|
462
|
-
const constValue = commandValue.const;
|
|
463
|
-
return typeof constValue === "string" ? constValue : void 0;
|
|
464
|
-
}
|
|
465
|
-
/** Map shared string constraints to JSON Schema properties. @internal */
|
|
466
|
-
function stringConstraintsToJsonSchemaProperties(constraints) {
|
|
467
|
-
const result = {};
|
|
468
|
-
const minLength = constraints?.nonEmpty === true ? Math.max(constraints.minLength ?? 1, 1) : constraints?.minLength;
|
|
469
|
-
if (minLength !== void 0) result.minLength = minLength;
|
|
470
|
-
if (constraints?.maxLength !== void 0) result.maxLength = constraints.maxLength;
|
|
471
|
-
if (constraints?.pattern !== void 0) result.pattern = constraints.pattern.source;
|
|
472
|
-
return result;
|
|
473
|
-
}
|
|
474
|
-
function flagToJsonSchemaType(schema) {
|
|
475
|
-
const result = {};
|
|
476
|
-
switch (schema.kind) {
|
|
477
|
-
case "string":
|
|
478
|
-
result.type = "string";
|
|
479
|
-
Object.assign(result, stringConstraintsToJsonSchemaProperties(schema.stringConstraints));
|
|
480
|
-
break;
|
|
481
|
-
case "number": {
|
|
482
|
-
const constraints = schema.numberConstraints;
|
|
483
|
-
result.type = constraints?.int === true ? "integer" : "number";
|
|
484
|
-
if (constraints?.min !== void 0) result.minimum = constraints.min;
|
|
485
|
-
if (constraints?.max !== void 0) result.maximum = constraints.max;
|
|
486
|
-
break;
|
|
487
|
-
}
|
|
488
|
-
case "boolean":
|
|
489
|
-
result.type = "boolean";
|
|
490
|
-
break;
|
|
491
|
-
case "enum":
|
|
492
|
-
result.type = "string";
|
|
493
|
-
if (schema.enumValues !== void 0) result.enum = [...schema.enumValues];
|
|
494
|
-
break;
|
|
495
|
-
case "array":
|
|
496
|
-
result.type = "array";
|
|
497
|
-
if (schema.elementSchema !== void 0) result.items = flagToJsonSchemaType(schema.elementSchema);
|
|
498
|
-
break;
|
|
499
|
-
case "custom": break;
|
|
500
|
-
case "count":
|
|
501
|
-
result.type = "integer";
|
|
502
|
-
result.minimum = 0;
|
|
503
|
-
break;
|
|
504
|
-
case "keyValue":
|
|
505
|
-
result.type = "object";
|
|
506
|
-
result.additionalProperties = schema.elementSchema === void 0 ? { type: "string" } : flagToJsonSchemaType(schema.elementSchema);
|
|
507
|
-
}
|
|
508
|
-
if (schema.description !== void 0) result.description = resolvePlainHelpDescription(schema.description);
|
|
509
|
-
if (isJsonSerializable(schema.defaultValue)) result.default = schema.defaultValue;
|
|
510
|
-
if (schema.deprecated !== void 0) result.deprecated = schema.deprecated;
|
|
511
|
-
return result;
|
|
512
|
-
}
|
|
513
|
-
function argToJsonSchemaType(schema) {
|
|
514
|
-
const kind = argKindToType(schema);
|
|
515
|
-
const result = schema.variadic && schema.kind !== "keyValue" ? {
|
|
516
|
-
type: "array",
|
|
517
|
-
items: kind
|
|
518
|
-
} : { ...kind };
|
|
519
|
-
if (schema.description !== void 0) result.description = resolvePlainHelpDescription(schema.description);
|
|
520
|
-
if (isJsonSerializable(schema.defaultValue)) result.default = schema.defaultValue;
|
|
521
|
-
if (schema.deprecated !== void 0) result.deprecated = schema.deprecated;
|
|
522
|
-
return result;
|
|
523
|
-
}
|
|
524
|
-
/** Map an arg's kind to a JSON Schema type fragment. */
|
|
525
|
-
function argKindToType(schema) {
|
|
526
|
-
switch (schema.kind) {
|
|
527
|
-
case "string": return {
|
|
528
|
-
type: "string",
|
|
529
|
-
...stringConstraintsToJsonSchemaProperties(schema.stringConstraints)
|
|
530
|
-
};
|
|
531
|
-
case "number": {
|
|
532
|
-
const constraints = schema.numberConstraints;
|
|
533
|
-
const result = { type: constraints?.int === true ? "integer" : "number" };
|
|
534
|
-
if (constraints?.min !== void 0) result.minimum = constraints.min;
|
|
535
|
-
if (constraints?.max !== void 0) result.maximum = constraints.max;
|
|
536
|
-
return result;
|
|
537
|
-
}
|
|
538
|
-
case "enum": {
|
|
539
|
-
const result = { type: "string" };
|
|
540
|
-
if (schema.enumValues !== void 0) result.enum = [...schema.enumValues];
|
|
541
|
-
return result;
|
|
542
|
-
}
|
|
543
|
-
case "boolean": return { type: "boolean" };
|
|
544
|
-
case "keyValue": return {
|
|
545
|
-
type: "object",
|
|
546
|
-
additionalProperties: schema.elementSchema === void 0 ? { type: "string" } : argKindToType(schema.elementSchema)
|
|
547
|
-
};
|
|
548
|
-
case "custom": return {};
|
|
549
|
-
}
|
|
550
|
-
}
|
|
551
|
-
/**
|
|
552
|
-
* Check whether a value can survive a JSON round-trip.
|
|
553
|
-
*
|
|
554
|
-
* Returns `false` for functions, symbols, bigints, non-finite numbers, and
|
|
555
|
-
* objects containing them. Used to guard default-value inclusion in
|
|
556
|
-
* serialized output.
|
|
557
|
-
*/
|
|
558
|
-
function isJsonSerializable(value, seen = /* @__PURE__ */ new WeakSet()) {
|
|
559
|
-
if (value === void 0) return false;
|
|
560
|
-
if (value === null) return true;
|
|
561
|
-
const t = typeof value;
|
|
562
|
-
if (t === "string" || t === "boolean") return true;
|
|
563
|
-
if (t === "number") return Number.isFinite(value);
|
|
564
|
-
if (t === "function" || t === "symbol" || t === "bigint") return false;
|
|
565
|
-
if (Array.isArray(value)) {
|
|
566
|
-
if (seen.has(value)) return false;
|
|
567
|
-
seen.add(value);
|
|
568
|
-
try {
|
|
569
|
-
return value.every((entry) => isJsonSerializable(entry, seen));
|
|
570
|
-
} finally {
|
|
571
|
-
seen.delete(value);
|
|
572
|
-
}
|
|
573
|
-
}
|
|
574
|
-
if (t === "object") {
|
|
575
|
-
const objectValue = value;
|
|
576
|
-
if (!isPlainJsonObject(objectValue)) return false;
|
|
577
|
-
if (seen.has(objectValue)) return false;
|
|
578
|
-
seen.add(objectValue);
|
|
579
|
-
try {
|
|
580
|
-
return Object.values(objectValue).every((entry) => isJsonSerializable(entry, seen));
|
|
581
|
-
} finally {
|
|
582
|
-
seen.delete(objectValue);
|
|
583
|
-
}
|
|
584
|
-
}
|
|
585
|
-
return false;
|
|
586
|
-
}
|
|
587
|
-
/**
|
|
588
|
-
* Check whether an object is a plain JSON object.
|
|
589
|
-
*
|
|
590
|
-
* Accepts objects with `Object.prototype` or a null prototype, which are the
|
|
591
|
-
* only object shapes that round-trip through JSON as structural objects.
|
|
592
|
-
*
|
|
593
|
-
* @internal
|
|
594
|
-
*/
|
|
595
|
-
function isPlainJsonObject(value) {
|
|
596
|
-
const proto = Object.getPrototypeOf(value);
|
|
597
|
-
return proto === Object.prototype || proto === null;
|
|
598
|
-
}
|
|
599
|
-
function withDefinitionDescriptions(schema, descriptions) {
|
|
600
|
-
const propertiesValue = schema.properties;
|
|
601
|
-
const describedProperties = typeof propertiesValue === "object" && propertiesValue !== null && isPlainJsonObject(propertiesValue) && descriptions.properties !== void 0 ? Object.fromEntries(Object.entries(propertiesValue).map(([name, propertySchema]) => {
|
|
602
|
-
const propertyDescriptions = descriptions.properties?.[name];
|
|
603
|
-
if (propertyDescriptions === void 0 || typeof propertySchema !== "object" || propertySchema === null || !isPlainJsonObject(propertySchema)) return [name, propertySchema];
|
|
604
|
-
return [name, withDefinitionDescriptions(propertySchema, propertyDescriptions)];
|
|
605
|
-
})) : void 0;
|
|
606
|
-
return {
|
|
607
|
-
...schema,
|
|
608
|
-
...descriptions.description !== void 0 ? { description: descriptions.description } : {},
|
|
609
|
-
...describedProperties !== void 0 ? { properties: describedProperties } : {}
|
|
610
|
-
};
|
|
611
|
-
}
|
|
612
|
-
function withDefinitionMetaSchemaDescriptions(schema, descriptions) {
|
|
613
|
-
const describedRoot = withDefinitionDescriptions(schema, descriptions.root);
|
|
614
|
-
const defsValue = describedRoot.$defs;
|
|
615
|
-
if (typeof defsValue !== "object" || defsValue === null || !isPlainJsonObject(defsValue)) return describedRoot;
|
|
616
|
-
return {
|
|
617
|
-
...describedRoot,
|
|
618
|
-
$defs: Object.fromEntries(Object.entries(defsValue).map(([name, defSchema]) => {
|
|
619
|
-
const defDescriptions = descriptions.defs[name];
|
|
620
|
-
if (defDescriptions === void 0 || typeof defSchema !== "object" || defSchema === null || !isPlainJsonObject(defSchema)) return [name, defSchema];
|
|
621
|
-
return [name, withDefinitionDescriptions(defSchema, defDescriptions)];
|
|
622
|
-
}))
|
|
623
|
-
};
|
|
624
|
-
}
|
|
625
|
-
/**
|
|
626
|
-
* Command-fragment property schemas shared by the nested `command` def and
|
|
627
|
-
* the standalone `commandDocument` def, so the two cannot drift.
|
|
628
|
-
*/
|
|
629
|
-
const commandFragmentProperties = {
|
|
630
|
-
name: { type: "string" },
|
|
631
|
-
description: { type: "string" },
|
|
632
|
-
aliases: {
|
|
633
|
-
type: "array",
|
|
634
|
-
items: { type: "string" }
|
|
635
|
-
},
|
|
636
|
-
hidden: { const: true },
|
|
637
|
-
examples: {
|
|
638
|
-
type: "array",
|
|
639
|
-
items: { $ref: "#/$defs/example" }
|
|
640
|
-
},
|
|
641
|
-
flags: {
|
|
642
|
-
type: "object",
|
|
643
|
-
additionalProperties: { $ref: "#/$defs/flag" }
|
|
644
|
-
},
|
|
645
|
-
args: {
|
|
646
|
-
type: "array",
|
|
647
|
-
items: { $ref: "#/$defs/arg" }
|
|
648
|
-
},
|
|
649
|
-
commands: {
|
|
650
|
-
type: "array",
|
|
651
|
-
items: { $ref: "#/$defs/command" }
|
|
652
|
-
}
|
|
653
|
-
};
|
|
654
|
-
/**
|
|
655
|
-
* Property schemas carried by a named positional definition.
|
|
656
|
-
*/
|
|
657
|
-
const argValueFragmentProperties = {
|
|
658
|
-
kind: { enum: [
|
|
659
|
-
"string",
|
|
660
|
-
"number",
|
|
661
|
-
"boolean",
|
|
662
|
-
"enum",
|
|
663
|
-
"custom",
|
|
664
|
-
"keyValue"
|
|
665
|
-
] },
|
|
666
|
-
presence: { enum: [
|
|
667
|
-
"required",
|
|
668
|
-
"optional",
|
|
669
|
-
"defaulted"
|
|
670
|
-
] },
|
|
671
|
-
variadic: { const: true },
|
|
672
|
-
stdin: { $ref: "#/$defs/stdin" },
|
|
673
|
-
defaultValue: {},
|
|
674
|
-
description: { type: "string" },
|
|
675
|
-
envVar: { type: "string" },
|
|
676
|
-
configPath: { type: "string" },
|
|
677
|
-
enumValues: {
|
|
678
|
-
type: "array",
|
|
679
|
-
items: { type: "string" }
|
|
680
|
-
},
|
|
681
|
-
elementSchema: { $ref: "#/$defs/argElement" },
|
|
682
|
-
numberConstraints: { $ref: "#/$defs/numberConstraints" },
|
|
683
|
-
stringConstraints: { $ref: "#/$defs/stringConstraints" },
|
|
684
|
-
pathChecks: { $ref: "#/$defs/pathChecks" },
|
|
685
|
-
valueHint: { type: "string" },
|
|
686
|
-
separator: {
|
|
687
|
-
type: "string",
|
|
688
|
-
minLength: 1
|
|
689
|
-
},
|
|
690
|
-
split: { $ref: "#/$defs/split" },
|
|
691
|
-
duplicateKeys: { enum: [...DUPLICATE_KEYS] },
|
|
692
|
-
unique: { const: true },
|
|
693
|
-
prompt: { $ref: "#/$defs/prompt" },
|
|
694
|
-
deprecated: { oneOf: [{ type: "string" }, { const: true }] }
|
|
695
|
-
};
|
|
696
|
-
/** Property schemas supported by a key-value entry element. */
|
|
697
|
-
const argElementFragmentProperties = {
|
|
698
|
-
kind: { enum: [
|
|
699
|
-
"string",
|
|
700
|
-
"number",
|
|
701
|
-
"boolean",
|
|
702
|
-
"enum",
|
|
703
|
-
"custom"
|
|
704
|
-
] },
|
|
705
|
-
presence: { const: "required" },
|
|
706
|
-
enumValues: {
|
|
707
|
-
type: "array",
|
|
708
|
-
items: { type: "string" }
|
|
709
|
-
},
|
|
710
|
-
numberConstraints: { $ref: "#/$defs/numberConstraints" },
|
|
711
|
-
stringConstraints: { $ref: "#/$defs/stringConstraints" },
|
|
712
|
-
pathChecks: { $ref: "#/$defs/pathChecks" },
|
|
713
|
-
valueHint: { type: "string" }
|
|
714
|
-
};
|
|
715
|
-
/**
|
|
716
|
-
* JSON Schema (draft 2020-12) that validates the output of {@link generateSchema}.
|
|
717
|
-
*
|
|
718
|
-
* Hosted at {@link DEFINITION_SCHEMA_URL} for `$schema` resolution. Also
|
|
719
|
-
* exported so tooling can validate definition documents without a network
|
|
720
|
-
* round-trip.
|
|
721
|
-
*
|
|
722
|
-
* @example
|
|
723
|
-
* ```ts
|
|
724
|
-
* import Ajv from 'ajv/dist/2020';
|
|
725
|
-
* import { definitionMetaSchema, generateSchema } from '@kjanat/dreamcli';
|
|
726
|
-
*
|
|
727
|
-
* const ajv = new Ajv();
|
|
728
|
-
* const validate = ajv.compile(definitionMetaSchema);
|
|
729
|
-
* const valid = validate(generateSchema(myCli.schema));
|
|
730
|
-
* ```
|
|
731
|
-
*/
|
|
732
|
-
const definitionMetaSchema = withDefinitionMetaSchemaDescriptions({
|
|
733
|
-
$schema: JSON_SCHEMA_DRAFT,
|
|
734
|
-
$id: DEFINITION_SCHEMA_URL,
|
|
735
|
-
title: "@kjanat/dreamcli definition schema",
|
|
736
|
-
description: "Describes the structure of a CLI built with dreamcli — commands, flags, args, types, constraints, env bindings, and prompts.",
|
|
737
|
-
type: "object",
|
|
738
|
-
additionalProperties: false,
|
|
739
|
-
properties: {
|
|
740
|
-
$schema: { const: DEFINITION_SCHEMA_URL },
|
|
741
|
-
schemaVersion: { const: 1 },
|
|
742
|
-
name: { type: "string" },
|
|
743
|
-
version: { type: "string" },
|
|
744
|
-
description: { type: "string" },
|
|
745
|
-
defaultCommand: { $ref: "#/$defs/command" },
|
|
746
|
-
commands: {
|
|
747
|
-
type: "array",
|
|
748
|
-
items: { $ref: "#/$defs/command" }
|
|
749
|
-
}
|
|
750
|
-
},
|
|
751
|
-
required: [
|
|
752
|
-
"$schema",
|
|
753
|
-
"schemaVersion",
|
|
754
|
-
"name",
|
|
755
|
-
"commands"
|
|
756
|
-
],
|
|
757
|
-
$defs: {
|
|
758
|
-
command: {
|
|
759
|
-
type: "object",
|
|
760
|
-
additionalProperties: false,
|
|
761
|
-
properties: commandFragmentProperties,
|
|
762
|
-
required: [
|
|
763
|
-
"name",
|
|
764
|
-
"flags",
|
|
765
|
-
"args",
|
|
766
|
-
"commands"
|
|
767
|
-
]
|
|
768
|
-
},
|
|
769
|
-
commandDocument: {
|
|
770
|
-
type: "object",
|
|
771
|
-
additionalProperties: false,
|
|
772
|
-
properties: {
|
|
773
|
-
schemaVersion: { const: 1 },
|
|
774
|
-
...commandFragmentProperties
|
|
775
|
-
},
|
|
776
|
-
required: [
|
|
777
|
-
"schemaVersion",
|
|
778
|
-
"name",
|
|
779
|
-
"flags",
|
|
780
|
-
"args",
|
|
781
|
-
"commands"
|
|
782
|
-
]
|
|
783
|
-
},
|
|
784
|
-
flag: {
|
|
785
|
-
type: "object",
|
|
786
|
-
additionalProperties: false,
|
|
787
|
-
properties: {
|
|
788
|
-
kind: { enum: [
|
|
789
|
-
"string",
|
|
790
|
-
"number",
|
|
791
|
-
"boolean",
|
|
792
|
-
"enum",
|
|
793
|
-
"array",
|
|
794
|
-
"custom",
|
|
795
|
-
"count",
|
|
796
|
-
"keyValue"
|
|
797
|
-
] },
|
|
798
|
-
presence: { enum: [
|
|
799
|
-
"optional",
|
|
800
|
-
"required",
|
|
801
|
-
"defaulted"
|
|
802
|
-
] },
|
|
803
|
-
defaultValue: {},
|
|
804
|
-
aliases: {
|
|
805
|
-
type: "array",
|
|
806
|
-
items: { type: "string" }
|
|
807
|
-
},
|
|
808
|
-
stdin: { $ref: "#/$defs/stdin" },
|
|
809
|
-
envVar: { type: "string" },
|
|
810
|
-
configPath: { type: "string" },
|
|
811
|
-
description: { type: "string" },
|
|
812
|
-
enumValues: {
|
|
813
|
-
type: "array",
|
|
814
|
-
items: { type: "string" }
|
|
815
|
-
},
|
|
816
|
-
numberConstraints: { $ref: "#/$defs/numberConstraints" },
|
|
817
|
-
stringConstraints: { $ref: "#/$defs/stringConstraints" },
|
|
818
|
-
elementSchema: { $ref: "#/$defs/flag" },
|
|
819
|
-
separator: {
|
|
820
|
-
type: "string",
|
|
821
|
-
minLength: 1
|
|
822
|
-
},
|
|
823
|
-
split: { $ref: "#/$defs/split" },
|
|
824
|
-
duplicateKeys: { enum: [...DUPLICATE_KEYS] },
|
|
825
|
-
unique: { const: true },
|
|
826
|
-
pathChecks: { $ref: "#/$defs/pathChecks" },
|
|
827
|
-
valueHint: { type: "string" },
|
|
828
|
-
prompt: { $ref: "#/$defs/prompt" },
|
|
829
|
-
deprecated: { oneOf: [{ type: "string" }, { const: true }] },
|
|
830
|
-
propagate: { const: true },
|
|
831
|
-
negation: { $ref: "#/$defs/negation" },
|
|
832
|
-
duplicates: { enum: [
|
|
833
|
-
"last",
|
|
834
|
-
"first",
|
|
835
|
-
"error"
|
|
836
|
-
] }
|
|
837
|
-
},
|
|
838
|
-
required: ["kind", "presence"]
|
|
839
|
-
},
|
|
840
|
-
stdin: {
|
|
841
|
-
type: "object",
|
|
842
|
-
additionalProperties: false,
|
|
843
|
-
properties: {
|
|
844
|
-
when: { enum: [
|
|
845
|
-
"dash",
|
|
846
|
-
"missing",
|
|
847
|
-
"dash-or-missing"
|
|
848
|
-
] },
|
|
849
|
-
consume: { enum: ["exclusive", "broadcast"] },
|
|
850
|
-
trim: { type: "boolean" }
|
|
851
|
-
},
|
|
852
|
-
required: ["when", "consume"]
|
|
853
|
-
},
|
|
854
|
-
split: {
|
|
855
|
-
type: "object",
|
|
856
|
-
additionalProperties: false,
|
|
857
|
-
properties: {
|
|
858
|
-
env: { $ref: "#/$defs/splitPolicy" },
|
|
859
|
-
stdin: { $ref: "#/$defs/splitPolicy" }
|
|
860
|
-
}
|
|
861
|
-
},
|
|
862
|
-
splitPolicy: {
|
|
863
|
-
type: "object",
|
|
864
|
-
additionalProperties: false,
|
|
865
|
-
properties: {
|
|
866
|
-
format: { enum: [
|
|
867
|
-
"whole",
|
|
868
|
-
"delimiter",
|
|
869
|
-
"lines",
|
|
870
|
-
"json"
|
|
871
|
-
] },
|
|
872
|
-
delimiter: {
|
|
873
|
-
type: "string",
|
|
874
|
-
minLength: 1
|
|
875
|
-
}
|
|
876
|
-
},
|
|
877
|
-
required: ["format"],
|
|
878
|
-
oneOf: [{
|
|
879
|
-
properties: { format: { const: "delimiter" } },
|
|
880
|
-
required: ["format", "delimiter"]
|
|
881
|
-
}, {
|
|
882
|
-
properties: { format: { enum: [
|
|
883
|
-
"whole",
|
|
884
|
-
"lines",
|
|
885
|
-
"json"
|
|
886
|
-
] } },
|
|
887
|
-
not: { required: ["delimiter"] }
|
|
888
|
-
}]
|
|
889
|
-
},
|
|
890
|
-
negation: {
|
|
891
|
-
type: "object",
|
|
892
|
-
additionalProperties: false,
|
|
893
|
-
properties: {
|
|
894
|
-
alias: { type: "string" },
|
|
895
|
-
hidden: { const: true }
|
|
896
|
-
}
|
|
897
|
-
},
|
|
898
|
-
numberConstraints: {
|
|
899
|
-
type: "object",
|
|
900
|
-
additionalProperties: false,
|
|
901
|
-
properties: {
|
|
902
|
-
min: { type: "number" },
|
|
903
|
-
max: { type: "number" },
|
|
904
|
-
int: { type: "boolean" },
|
|
905
|
-
finite: { type: "boolean" }
|
|
906
|
-
}
|
|
907
|
-
},
|
|
908
|
-
stringConstraints: {
|
|
909
|
-
type: "object",
|
|
910
|
-
additionalProperties: false,
|
|
911
|
-
properties: {
|
|
912
|
-
nonEmpty: { type: "boolean" },
|
|
913
|
-
minLength: {
|
|
914
|
-
type: "integer",
|
|
915
|
-
minimum: 0
|
|
916
|
-
},
|
|
917
|
-
maxLength: {
|
|
918
|
-
type: "integer",
|
|
919
|
-
minimum: 0
|
|
920
|
-
},
|
|
921
|
-
pattern: {
|
|
922
|
-
type: "object",
|
|
923
|
-
additionalProperties: false,
|
|
924
|
-
properties: {
|
|
925
|
-
source: { type: "string" },
|
|
926
|
-
flags: { type: "string" }
|
|
927
|
-
},
|
|
928
|
-
required: ["source", "flags"]
|
|
929
|
-
}
|
|
930
|
-
}
|
|
931
|
-
},
|
|
932
|
-
pathChecks: {
|
|
933
|
-
type: "object",
|
|
934
|
-
additionalProperties: false,
|
|
935
|
-
properties: {
|
|
936
|
-
mustExist: { type: "boolean" },
|
|
937
|
-
type: { enum: ["file", "directory"] },
|
|
938
|
-
create: { const: true }
|
|
939
|
-
},
|
|
940
|
-
required: ["mustExist"]
|
|
941
|
-
},
|
|
942
|
-
argElement: {
|
|
943
|
-
type: "object",
|
|
944
|
-
additionalProperties: false,
|
|
945
|
-
properties: argElementFragmentProperties,
|
|
946
|
-
required: ["kind", "presence"]
|
|
947
|
-
},
|
|
948
|
-
arg: {
|
|
949
|
-
type: "object",
|
|
950
|
-
additionalProperties: false,
|
|
951
|
-
properties: {
|
|
952
|
-
name: { type: "string" },
|
|
953
|
-
...argValueFragmentProperties
|
|
954
|
-
},
|
|
955
|
-
required: [
|
|
956
|
-
"name",
|
|
957
|
-
"kind",
|
|
958
|
-
"presence"
|
|
959
|
-
],
|
|
960
|
-
anyOf: [{ not: { required: ["elementSchema"] } }, {
|
|
961
|
-
properties: { kind: { const: "keyValue" } },
|
|
962
|
-
required: ["kind"]
|
|
963
|
-
}]
|
|
964
|
-
},
|
|
965
|
-
prompt: {
|
|
966
|
-
type: "object",
|
|
967
|
-
additionalProperties: false,
|
|
968
|
-
properties: {
|
|
969
|
-
kind: { enum: [
|
|
970
|
-
"confirm",
|
|
971
|
-
"input",
|
|
972
|
-
"select",
|
|
973
|
-
"multiselect"
|
|
974
|
-
] },
|
|
975
|
-
message: { type: "string" },
|
|
976
|
-
placeholder: { type: "string" },
|
|
977
|
-
choices: {
|
|
978
|
-
type: "array",
|
|
979
|
-
items: { $ref: "#/$defs/choice" }
|
|
980
|
-
},
|
|
981
|
-
min: { type: "integer" },
|
|
982
|
-
max: { type: "integer" }
|
|
983
|
-
},
|
|
984
|
-
required: ["kind", "message"]
|
|
985
|
-
},
|
|
986
|
-
choice: {
|
|
987
|
-
type: "object",
|
|
988
|
-
additionalProperties: false,
|
|
989
|
-
properties: {
|
|
990
|
-
value: { type: "string" },
|
|
991
|
-
label: { type: "string" },
|
|
992
|
-
description: { type: "string" }
|
|
993
|
-
},
|
|
994
|
-
required: ["value"]
|
|
995
|
-
},
|
|
996
|
-
example: {
|
|
997
|
-
type: "object",
|
|
998
|
-
additionalProperties: false,
|
|
999
|
-
properties: {
|
|
1000
|
-
command: { type: "string" },
|
|
1001
|
-
description: { type: "string" }
|
|
1002
|
-
},
|
|
1003
|
-
required: ["command"]
|
|
1004
|
-
}
|
|
1005
|
-
}
|
|
1006
|
-
}, definitionMetaSchemaDescriptions);
|
|
1007
|
-
//#endregion
|
|
1008
|
-
export { DEFINITION_SCHEMA_URL, DEFINITION_SCHEMA_VERSION, definitionMetaSchema, generateCommandSchema, generateInputSchema, generateSchema };
|