@kjanat/dreamcli 3.0.0-rc.1 → 3.0.0-rc.3
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 +37 -1
- package/dist/core/cli/dispatch.mjs +214 -1
- package/dist/core/cli/help-links.mjs +41 -1
- package/dist/core/cli/index.mjs +901 -1
- package/dist/core/cli/planner.mjs +300 -1
- package/dist/core/cli/plugin.mjs +41 -1
- package/dist/core/cli/propagate.mjs +57 -1
- package/dist/core/cli/root-help.mjs +208 -4
- package/dist/core/cli/root-surface.mjs +27 -1
- package/dist/core/cli/runtime-preflight.mjs +168 -1
- package/dist/core/completion/index.mjs +90 -1
- package/dist/core/completion/shells/bash.mjs +304 -3
- package/dist/core/completion/shells/fish.mjs +159 -2
- package/dist/core/completion/shells/powershell.mjs +353 -2
- package/dist/core/completion/shells/shared.mjs +154 -1
- package/dist/core/completion/shells/zsh.mjs +244 -2
- package/dist/core/config/index.mjs +246 -1
- package/dist/core/config/package-json.mjs +385 -3
- package/dist/core/errors/index.mjs +87 -1
- package/dist/core/execution/index.mjs +189 -1
- package/dist/core/help/ansi.mjs +122 -2
- package/dist/core/help/index.mjs +329 -7
- package/dist/core/json-schema/index.mjs +487 -9
- package/dist/core/json-schema/meta-descriptions.generated.mjs +93 -28
- package/dist/core/output/activity.mjs +452 -1
- package/dist/core/output/bind.mjs +56 -1
- package/dist/core/output/contracts.mjs +57 -1
- package/dist/core/output/display-value.mjs +32 -1
- package/dist/core/output/index.d.mts +21 -0
- package/dist/core/output/index.mjs +442 -2
- package/dist/core/output/renderers.mjs +46 -1
- package/dist/core/output/writer.mjs +12 -1
- package/dist/core/parse/index.mjs +555 -1
- package/dist/core/prompt/index.d.mts +0 -1
- package/dist/core/prompt/index.mjs +348 -6
- package/dist/core/resolve/args.mjs +105 -1
- package/dist/core/resolve/coerce.mjs +279 -1
- package/dist/core/resolve/config.mjs +19 -1
- package/dist/core/resolve/errors.mjs +140 -2
- package/dist/core/resolve/flags.mjs +196 -1
- package/dist/core/resolve/index.mjs +85 -1
- package/dist/core/resolve/property.d.mts +0 -1
- package/dist/core/resolve/property.mjs +45 -1
- package/dist/core/schema/arg.mjs +463 -1
- package/dist/core/schema/command.d.mts +18 -0
- package/dist/core/schema/command.mjs +712 -1
- package/dist/core/schema/flag.mjs +453 -1
- package/dist/core/schema/middleware.mjs +41 -1
- package/dist/core/schema/number-constraints.mjs +60 -1
- package/dist/core/schema-dsl/runtime.mjs +271 -2
- package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
- package/dist/core/testkit/index.mjs +83 -1
- package/dist/index.d.mts +2 -1
- package/dist/index.mjs +22 -1
- package/dist/runtime/adapter.mjs +82 -1
- package/dist/runtime/auto.mjs +46 -1
- package/dist/runtime/bun.mjs +28 -1
- package/dist/runtime/deno.mjs +217 -2
- package/dist/runtime/detect.mjs +45 -1
- package/dist/runtime/node.mjs +169 -2
- package/dist/runtime/paths.mjs +48 -1
- package/dist/runtime.mjs +7 -1
- package/dist/strings.mjs +22 -1
- package/dist/testkit.mjs +5 -1
- package/dist/version.d.mts +7 -3
- package/dist/version.mjs +7 -1
- package/package.json +21 -26
- package/src/core/cli/dispatch.ts +0 -355
- package/src/core/cli/help-links.ts +0 -82
- package/src/core/cli/index.ts +0 -1614
- package/src/core/cli/planner.ts +0 -656
- package/src/core/cli/plugin.ts +0 -117
- package/src/core/cli/propagate.ts +0 -97
- package/src/core/cli/root-help.ts +0 -342
- package/src/core/cli/root-surface.ts +0 -87
- package/src/core/cli/runtime-preflight.ts +0 -456
- package/src/core/completion/index.ts +0 -138
- package/src/core/completion/shells/bash.ts +0 -459
- package/src/core/completion/shells/fish.ts +0 -259
- package/src/core/completion/shells/powershell.ts +0 -439
- package/src/core/completion/shells/shared.ts +0 -310
- package/src/core/completion/shells/zsh.ts +0 -381
- package/src/core/config/index.ts +0 -417
- package/src/core/config/package-json.ts +0 -560
- package/src/core/errors/index.ts +0 -193
- package/src/core/execution/index.ts +0 -265
- package/src/core/help/ansi.ts +0 -144
- package/src/core/help/index.ts +0 -563
- package/src/core/json-schema/index.ts +0 -910
- package/src/core/json-schema/meta-descriptions.generated.ts +0 -202
- package/src/core/output/activity.ts +0 -575
- package/src/core/output/bind.ts +0 -59
- package/src/core/output/contracts.ts +0 -194
- package/src/core/output/display-value.ts +0 -48
- package/src/core/output/index.ts +0 -704
- package/src/core/output/renderers.ts +0 -125
- package/src/core/output/writer.ts +0 -46
- package/src/core/parse/index.ts +0 -742
- package/src/core/prompt/index.ts +0 -623
- package/src/core/resolve/args.ts +0 -144
- package/src/core/resolve/coerce.ts +0 -500
- package/src/core/resolve/config.ts +0 -26
- package/src/core/resolve/contracts.ts +0 -135
- package/src/core/resolve/errors.ts +0 -227
- package/src/core/resolve/flags.ts +0 -269
- package/src/core/resolve/index.ts +0 -108
- package/src/core/resolve/property.ts +0 -99
- package/src/core/schema/activity.ts +0 -240
- package/src/core/schema/arg.ts +0 -841
- package/src/core/schema/command.ts +0 -1500
- package/src/core/schema/flag.ts +0 -917
- package/src/core/schema/index.ts +0 -96
- package/src/core/schema/middleware.ts +0 -171
- package/src/core/schema/number-constraints.ts +0 -153
- package/src/core/schema/prompt.ts +0 -171
- package/src/core/schema/run.ts +0 -198
- package/src/core/schema-dsl/index.ts +0 -109
- package/src/core/schema-dsl/parse.ts +0 -262
- package/src/core/schema-dsl/runtime.ts +0 -609
- package/src/core/schema-dsl/to-json-schema.ts +0 -102
- package/src/core/testkit/index.ts +0 -147
- package/src/index.ts +0 -181
- package/src/runtime/adapter.ts +0 -303
- package/src/runtime/auto.ts +0 -86
- package/src/runtime/bun.ts +0 -48
- package/src/runtime/deno.ts +0 -367
- package/src/runtime/detect.ts +0 -105
- package/src/runtime/index.ts +0 -21
- package/src/runtime/node-builtins.d.ts +0 -27
- package/src/runtime/node.ts +0 -289
- package/src/runtime/paths.ts +0 -64
- package/src/runtime/support.ts +0 -77
- package/src/runtime.ts +0 -31
- package/src/schema.ts +0 -16
- package/src/strings.ts +0 -34
- package/src/testkit.ts +0 -25
- package/src/version.ts +0 -20
|
@@ -1 +1,85 @@
|
|
|
1
|
-
import{isValidationError
|
|
1
|
+
import { isValidationError } from "../errors/index.mjs";
|
|
2
|
+
import { collectValidationErrors, isNonEmpty, throwAggregatedErrors } from "./errors.mjs";
|
|
3
|
+
import { resolveArgs } from "./args.mjs";
|
|
4
|
+
import { resolveFlags } from "./flags.mjs";
|
|
5
|
+
//#region src/core/resolve/index.ts
|
|
6
|
+
/**
|
|
7
|
+
* Resolution chain: CLI -> env -> config -> prompt -> default.
|
|
8
|
+
*
|
|
9
|
+
* v0.1 implemented: **CLI parsed value -> default value**.
|
|
10
|
+
* v0.2 adds: **env variable resolution** and **config object resolution**
|
|
11
|
+
* between CLI and default.
|
|
12
|
+
* v0.3 adds: **prompt resolution** between config and default.
|
|
13
|
+
*
|
|
14
|
+
* The resolver takes raw {@linkcode ParseResult} (from the parser) and a
|
|
15
|
+
* {@linkcode CommandSchema}, applies the resolution chain, and validates
|
|
16
|
+
* that all required flags/args are present. On success it returns a
|
|
17
|
+
* {@linkcode ResolveResult} with fully resolved values; on failure it throws
|
|
18
|
+
* {@linkcode ValidationError}.
|
|
19
|
+
*
|
|
20
|
+
* @module dreamcli/core/resolve
|
|
21
|
+
*/
|
|
22
|
+
/**
|
|
23
|
+
* Resolve parsed values against a command schema.
|
|
24
|
+
*
|
|
25
|
+
* Low-level API: most applications should rely on `cli().run()`, `.execute()`,
|
|
26
|
+
* or `runCommand()`, which already call {@linkcode resolve} at the right time.
|
|
27
|
+
* Reach for this function when testing precedence rules directly or building
|
|
28
|
+
* custom execution flows around {@linkcode CommandSchema}.
|
|
29
|
+
*
|
|
30
|
+
* Resolution order:
|
|
31
|
+
* 1. CLI parsed value (from {@linkcode ParseResult})
|
|
32
|
+
* 2. Env variable (from {@linkcode ResolveOptions.env}, if flag declares `envVar`)
|
|
33
|
+
* 3. Config value (from {@linkcode ResolveOptions.config}, if flag declares `configPath`)
|
|
34
|
+
* 4. Prompt (from {@linkcode ResolveOptions.prompter}, if flag declares `prompt`)
|
|
35
|
+
* 5. Default value (from schema)
|
|
36
|
+
*
|
|
37
|
+
* After resolution, validates that all required flags and args have
|
|
38
|
+
* a value. Collects **all** validation errors before throwing, so the
|
|
39
|
+
* user sees every missing field at once.
|
|
40
|
+
*
|
|
41
|
+
* @param schema - The command schema defining flags and args
|
|
42
|
+
* @param parsed - Raw parsed values from the parser
|
|
43
|
+
* @param options - External state for the resolution chain
|
|
44
|
+
* @returns Fully resolved flag and arg values
|
|
45
|
+
* @throws {@linkcode ValidationError} if any required flag or arg is missing,
|
|
46
|
+
* or if an env/config value fails coercion
|
|
47
|
+
*
|
|
48
|
+
* @example
|
|
49
|
+
* ```ts
|
|
50
|
+
* const parsed = parse(deploy.schema, ['production']);
|
|
51
|
+
* const resolved = await resolve(deploy.schema, parsed, {
|
|
52
|
+
* env: { DEPLOY_REGION: 'eu' },
|
|
53
|
+
* });
|
|
54
|
+
* ```
|
|
55
|
+
*/
|
|
56
|
+
async function resolve(schema, parsed, options) {
|
|
57
|
+
const stdinData = options?.stdinData;
|
|
58
|
+
const env = options?.env ?? {};
|
|
59
|
+
const config = options?.config ?? {};
|
|
60
|
+
const prompter = options?.prompter;
|
|
61
|
+
const deprecations = [];
|
|
62
|
+
let flags = {};
|
|
63
|
+
let args = {};
|
|
64
|
+
const errors = [];
|
|
65
|
+
try {
|
|
66
|
+
flags = await resolveFlags(schema.flags, parsed.flags, env, config, prompter, schema.interactive, deprecations);
|
|
67
|
+
} catch (error) {
|
|
68
|
+
if (!isValidationError(error)) throw error;
|
|
69
|
+
errors.push(...collectValidationErrors(error));
|
|
70
|
+
}
|
|
71
|
+
try {
|
|
72
|
+
args = resolveArgs(schema.args, parsed.args, stdinData, env, deprecations);
|
|
73
|
+
} catch (error) {
|
|
74
|
+
if (!isValidationError(error)) throw error;
|
|
75
|
+
errors.push(...collectValidationErrors(error));
|
|
76
|
+
}
|
|
77
|
+
if (isNonEmpty(errors)) throwAggregatedErrors(errors);
|
|
78
|
+
return {
|
|
79
|
+
flags,
|
|
80
|
+
args,
|
|
81
|
+
deprecations
|
|
82
|
+
};
|
|
83
|
+
}
|
|
84
|
+
//#endregion
|
|
85
|
+
export { resolve };
|
|
@@ -1,7 +1,6 @@
|
|
|
1
1
|
import { NumberConstraints } from "../schema/number-constraints.mjs";
|
|
2
2
|
import { ArgSchema } from "../schema/arg.mjs";
|
|
3
3
|
import { FlagSchema } from "../schema/flag.mjs";
|
|
4
|
-
|
|
5
4
|
//#region src/core/resolve/property.d.ts
|
|
6
5
|
/** Flag/arg kinds that share a common coercion path. */
|
|
7
6
|
declare const SHARED_PROPERTY_MODEL_KINDS: readonly ['string', 'number', 'enum', 'custom'];
|
|
@@ -1 +1,45 @@
|
|
|
1
|
-
|
|
1
|
+
//#region src/core/resolve/property.ts
|
|
2
|
+
/** Extract the shared coercion slice from a flag schema, or `undefined` for boolean/array (handled separately). */
|
|
3
|
+
function toSharedFlagPropertySchema(schema) {
|
|
4
|
+
switch (schema.kind) {
|
|
5
|
+
case "string": return { kind: "string" };
|
|
6
|
+
case "number": return {
|
|
7
|
+
kind: "number",
|
|
8
|
+
numberConstraints: schema.numberConstraints
|
|
9
|
+
};
|
|
10
|
+
case "enum": return {
|
|
11
|
+
kind: "enum",
|
|
12
|
+
enumValues: schema.enumValues
|
|
13
|
+
};
|
|
14
|
+
case "custom": return schema.parseFn === void 0 ? { kind: "custom" } : {
|
|
15
|
+
kind: "custom",
|
|
16
|
+
parseFn: schema.parseFn
|
|
17
|
+
};
|
|
18
|
+
case "boolean":
|
|
19
|
+
case "array": return;
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
/** Extract the shared coercion slice from an arg schema (all arg kinds are shared). */
|
|
23
|
+
function toSharedArgPropertySchema(schema) {
|
|
24
|
+
switch (schema.kind) {
|
|
25
|
+
case "string": return { kind: "string" };
|
|
26
|
+
case "number": return {
|
|
27
|
+
kind: "number",
|
|
28
|
+
numberConstraints: schema.numberConstraints
|
|
29
|
+
};
|
|
30
|
+
case "enum": return {
|
|
31
|
+
kind: "enum",
|
|
32
|
+
enumValues: schema.enumValues
|
|
33
|
+
};
|
|
34
|
+
case "custom": {
|
|
35
|
+
if (schema.parseFn === void 0) return { kind: "custom" };
|
|
36
|
+
const parseFn = schema.parseFn;
|
|
37
|
+
return {
|
|
38
|
+
kind: "custom",
|
|
39
|
+
parseFn: (raw) => parseFn(typeof raw === "string" ? raw : String(raw))
|
|
40
|
+
};
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
//#endregion
|
|
45
|
+
export { toSharedArgPropertySchema, toSharedFlagPropertySchema };
|
package/dist/core/schema/arg.mjs
CHANGED
|
@@ -1 +1,463 @@
|
|
|
1
|
-
import{assertNumberConstraints
|
|
1
|
+
import { assertNumberConstraints } from "./number-constraints.mjs";
|
|
2
|
+
//#region src/core/schema/arg.ts
|
|
3
|
+
/**
|
|
4
|
+
* Positional argument schema builder with full type inference.
|
|
5
|
+
*
|
|
6
|
+
* Each factory (`arg.string()`, `arg.number()`, `arg.enum()`, `arg.custom()`) returns an
|
|
7
|
+
* immutable {@linkcode ArgBuilder} whose generic parameter tracks the value type,
|
|
8
|
+
* presence state, and variadic flag through the fluent chain.
|
|
9
|
+
*
|
|
10
|
+
* @module dreamcli/core/schema/arg
|
|
11
|
+
*/
|
|
12
|
+
/**
|
|
13
|
+
* Create a raw {@link ArgSchema} object with sensible defaults.
|
|
14
|
+
*
|
|
15
|
+
* Most consumers should prefer the higher-level {@link arg} factory, which
|
|
16
|
+
* returns an immutable {@link ArgBuilder} with type inference and fluent
|
|
17
|
+
* modifiers. `createArgSchema()` exists for advanced schema composition,
|
|
18
|
+
* targeted tests, or custom builders that need the plain runtime descriptor.
|
|
19
|
+
*
|
|
20
|
+
* `overrides` are shallow-merged on top of the default shape, so callers are
|
|
21
|
+
* responsible for preserving invariants such as variadic ordering and
|
|
22
|
+
* compatible `parseFn` / `kind` combinations.
|
|
23
|
+
*
|
|
24
|
+
* @param kind - Discriminator for the value type this arg accepts.
|
|
25
|
+
* @param overrides - Partial schema fields shallow-merged onto defaults.
|
|
26
|
+
* @returns A fully populated {@link ArgSchema}.
|
|
27
|
+
*
|
|
28
|
+
* @example
|
|
29
|
+
* ```ts
|
|
30
|
+
* const schema = createArgSchema('custom', {
|
|
31
|
+
* description: 'Hex color',
|
|
32
|
+
* parseFn: (raw) => `#${raw}`,
|
|
33
|
+
* });
|
|
34
|
+
* ```
|
|
35
|
+
*/
|
|
36
|
+
function createArgSchema(kind, overrides) {
|
|
37
|
+
return {
|
|
38
|
+
kind,
|
|
39
|
+
presence: "required",
|
|
40
|
+
variadic: false,
|
|
41
|
+
stdinMode: false,
|
|
42
|
+
defaultValue: void 0,
|
|
43
|
+
description: void 0,
|
|
44
|
+
envVar: void 0,
|
|
45
|
+
enumValues: void 0,
|
|
46
|
+
numberConstraints: void 0,
|
|
47
|
+
parseFn: void 0,
|
|
48
|
+
deprecated: void 0,
|
|
49
|
+
...overrides
|
|
50
|
+
};
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* Immutable positional argument schema builder.
|
|
54
|
+
*
|
|
55
|
+
* The type parameter `C` is a phantom that tracks the value type, presence,
|
|
56
|
+
* and variadic state through the fluent chain. Each modifier returns a **new**
|
|
57
|
+
* builder — the original is never mutated.
|
|
58
|
+
*
|
|
59
|
+
* @example
|
|
60
|
+
* ```ts
|
|
61
|
+
* // Full command with multiple args and modifiers
|
|
62
|
+
* import { command, arg } from '@kjanat/dreamcli';
|
|
63
|
+
*
|
|
64
|
+
* command('deploy')
|
|
65
|
+
* .arg('target', arg.string()
|
|
66
|
+
* .env('DEPLOY_TARGET')
|
|
67
|
+
* .describe('Deploy target'))
|
|
68
|
+
* .arg('port', arg.number()
|
|
69
|
+
* .env('PORT')
|
|
70
|
+
* .default(3000)
|
|
71
|
+
* .describe('Port number'))
|
|
72
|
+
* .arg('files', arg.string()
|
|
73
|
+
* .variadic()
|
|
74
|
+
* .optional()
|
|
75
|
+
* .describe('Extra config files'))
|
|
76
|
+
* .action(({ args }) => {
|
|
77
|
+
* args.target; // string (required, from CLI or $DEPLOY_TARGET)
|
|
78
|
+
* args.port; // number (defaulted, from CLI, $PORT, or 3000)
|
|
79
|
+
* args.files; // string[] (optional variadic)
|
|
80
|
+
* });
|
|
81
|
+
* ```
|
|
82
|
+
*
|
|
83
|
+
* @example
|
|
84
|
+
* ```ts
|
|
85
|
+
* // Type inference
|
|
86
|
+
* const target = arg.string();
|
|
87
|
+
* type T = InferArg<typeof target>; // string
|
|
88
|
+
*
|
|
89
|
+
* const opt = arg.string().optional();
|
|
90
|
+
* type O = InferArg<typeof opt>; // string | undefined
|
|
91
|
+
*
|
|
92
|
+
* const files = arg.string().variadic();
|
|
93
|
+
* type F = InferArg<typeof files>; // string[]
|
|
94
|
+
* ```
|
|
95
|
+
*/
|
|
96
|
+
var ArgBuilder = class ArgBuilder {
|
|
97
|
+
/** @internal Runtime schema descriptor. */
|
|
98
|
+
schema;
|
|
99
|
+
/**
|
|
100
|
+
* Create an arg builder from a pre-built schema descriptor.
|
|
101
|
+
*
|
|
102
|
+
* @param schema - Runtime descriptor for this positional argument.
|
|
103
|
+
*/
|
|
104
|
+
constructor(schema) {
|
|
105
|
+
this.schema = schema;
|
|
106
|
+
}
|
|
107
|
+
/**
|
|
108
|
+
* Mark the arg as required (this is the default for positional args).
|
|
109
|
+
* Produces an error if no value resolves from any configured source
|
|
110
|
+
* (CLI → stdin → env → default).
|
|
111
|
+
*
|
|
112
|
+
* @example
|
|
113
|
+
* ```ts
|
|
114
|
+
* arg.string().required() // explicit, same as default
|
|
115
|
+
*
|
|
116
|
+
* // In a command — omitting <target> causes a ValidationError:
|
|
117
|
+
* command('deploy')
|
|
118
|
+
* .arg('target', arg.string().required().describe('Deploy target'))
|
|
119
|
+
* // $ mycli deploy
|
|
120
|
+
* // Error: Missing required argument <target>
|
|
121
|
+
* ```
|
|
122
|
+
*
|
|
123
|
+
* @returns The builder (for chaining).
|
|
124
|
+
*/
|
|
125
|
+
required() {
|
|
126
|
+
return new ArgBuilder({
|
|
127
|
+
...this.schema,
|
|
128
|
+
presence: "required"
|
|
129
|
+
});
|
|
130
|
+
}
|
|
131
|
+
/**
|
|
132
|
+
* Mark the arg as optional. Handlers receive `undefined` when absent.
|
|
133
|
+
*
|
|
134
|
+
* @example
|
|
135
|
+
* ```ts
|
|
136
|
+
* arg.string().optional()
|
|
137
|
+
*
|
|
138
|
+
* // In a command — handler receives `undefined` when omitted:
|
|
139
|
+
* command('greet')
|
|
140
|
+
* .arg('name', arg.string().optional().describe('Who to greet'))
|
|
141
|
+
* .action(({ args }) => {
|
|
142
|
+
* args.name; // string | undefined
|
|
143
|
+
* });
|
|
144
|
+
* // $ mycli greet → args.name is undefined
|
|
145
|
+
* // $ mycli greet Alice → args.name is 'Alice'
|
|
146
|
+
* ```
|
|
147
|
+
*
|
|
148
|
+
* @returns The builder (for chaining).
|
|
149
|
+
*/
|
|
150
|
+
optional() {
|
|
151
|
+
return new ArgBuilder({
|
|
152
|
+
...this.schema,
|
|
153
|
+
presence: "optional"
|
|
154
|
+
});
|
|
155
|
+
}
|
|
156
|
+
/**
|
|
157
|
+
* Provide a default value. The arg becomes "always present" — handlers
|
|
158
|
+
* will never see `undefined`.
|
|
159
|
+
*
|
|
160
|
+
* The generic constraint `V extends C['valueType']` ensures the default
|
|
161
|
+
* matches the arg's declared type.
|
|
162
|
+
*
|
|
163
|
+
* Resolution order when extra sources are configured: CLI → stdin → env → **default**.
|
|
164
|
+
*
|
|
165
|
+
* @param value - Fallback used when no CLI value or env var resolves.
|
|
166
|
+
* @returns The builder (for chaining).
|
|
167
|
+
*
|
|
168
|
+
* @example
|
|
169
|
+
* ```ts
|
|
170
|
+
* arg.string().default('production')
|
|
171
|
+
* arg.number().default(3000)
|
|
172
|
+
*
|
|
173
|
+
* // In a command — default kicks in when CLI and env are both absent:
|
|
174
|
+
* command('deploy')
|
|
175
|
+
* .arg('env', arg.string()
|
|
176
|
+
* .env('DEPLOY_ENV')
|
|
177
|
+
* .default('staging')
|
|
178
|
+
* .describe('Target environment'))
|
|
179
|
+
* .action(({ args }) => {
|
|
180
|
+
* args.env; // string (never undefined)
|
|
181
|
+
* });
|
|
182
|
+
* // $ mycli deploy → 'staging' (default)
|
|
183
|
+
* // $ DEPLOY_ENV=prod mycli deploy → 'prod' (env)
|
|
184
|
+
* // $ mycli deploy production → 'production' (CLI)
|
|
185
|
+
* ```
|
|
186
|
+
*/
|
|
187
|
+
default(value) {
|
|
188
|
+
return new ArgBuilder({
|
|
189
|
+
...this.schema,
|
|
190
|
+
presence: "defaulted",
|
|
191
|
+
defaultValue: value
|
|
192
|
+
});
|
|
193
|
+
}
|
|
194
|
+
/**
|
|
195
|
+
* Mark this arg as variadic — it consumes all remaining positional
|
|
196
|
+
* arguments. The inferred type becomes `T[]`.
|
|
197
|
+
*
|
|
198
|
+
* A variadic arg must be the last positional in a command.
|
|
199
|
+
*
|
|
200
|
+
* @example
|
|
201
|
+
* ```ts
|
|
202
|
+
* arg.string().variadic()
|
|
203
|
+
*
|
|
204
|
+
* // In a command — collects all remaining positionals:
|
|
205
|
+
* command('build')
|
|
206
|
+
* .arg('entry', arg.string().describe('Main entry'))
|
|
207
|
+
* .arg('extras', arg.string().variadic().optional().describe('Extra files'))
|
|
208
|
+
* .action(({ args }) => {
|
|
209
|
+
* args.entry; // string
|
|
210
|
+
* args.extras; // string[]
|
|
211
|
+
* });
|
|
212
|
+
* // $ mycli build main.ts a.ts b.ts
|
|
213
|
+
* // → entry = 'main.ts', extras = ['a.ts', 'b.ts']
|
|
214
|
+
* ```
|
|
215
|
+
*
|
|
216
|
+
* @returns The builder (for chaining).
|
|
217
|
+
*/
|
|
218
|
+
variadic() {
|
|
219
|
+
return new ArgBuilder({
|
|
220
|
+
...this.schema,
|
|
221
|
+
variadic: true
|
|
222
|
+
});
|
|
223
|
+
}
|
|
224
|
+
/**
|
|
225
|
+
* Allow this arg to resolve from stdin when CLI input is missing.
|
|
226
|
+
*
|
|
227
|
+
* Resolution order becomes: CLI value -> stdin -> env -> default.
|
|
228
|
+
* Only one arg per command may enable stdin mode.
|
|
229
|
+
*
|
|
230
|
+
* @returns The builder (for chaining).
|
|
231
|
+
*
|
|
232
|
+
* @example
|
|
233
|
+
* ```ts
|
|
234
|
+
* arg.string().describe('Input text').stdin()
|
|
235
|
+
* // $ echo "hello" | mycli transform → input = 'hello' (from stdin)
|
|
236
|
+
* // $ mycli transform "hello" → input = 'hello' (from CLI)
|
|
237
|
+
* ```
|
|
238
|
+
*/
|
|
239
|
+
stdin() {
|
|
240
|
+
return new ArgBuilder({
|
|
241
|
+
...this.schema,
|
|
242
|
+
stdinMode: true
|
|
243
|
+
});
|
|
244
|
+
}
|
|
245
|
+
/**
|
|
246
|
+
* Bind to an environment variable.
|
|
247
|
+
*
|
|
248
|
+
* When the arg is not provided on the CLI, the resolver checks this
|
|
249
|
+
* env var before falling back to the default value. The env string is
|
|
250
|
+
* coerced to the arg's declared kind (passthrough for strings, parsed
|
|
251
|
+
* for numbers, run through `parseFn` for custom args).
|
|
252
|
+
*
|
|
253
|
+
* Resolution order when extra sources are configured: **CLI → stdin → env → default**.
|
|
254
|
+
*
|
|
255
|
+
* Help output shows `[env: VAR]` next to the arg description.
|
|
256
|
+
*
|
|
257
|
+
* @param varName - Environment variable name (e.g. `'DEPLOY_TARGET'`).
|
|
258
|
+
* @returns The builder (for chaining).
|
|
259
|
+
*
|
|
260
|
+
* @example
|
|
261
|
+
* ```ts
|
|
262
|
+
* command('deploy')
|
|
263
|
+
* .arg('target', arg.string().env('DEPLOY_TARGET').describe('Deploy target'))
|
|
264
|
+
* .arg('port', arg.number().env('PORT').default(3000))
|
|
265
|
+
* .action(({ args }) => {
|
|
266
|
+
* console.log(args.target); // from CLI, $DEPLOY_TARGET, or error
|
|
267
|
+
* console.log(args.port); // from CLI, $PORT, or 3000
|
|
268
|
+
* });
|
|
269
|
+
* ```
|
|
270
|
+
*/
|
|
271
|
+
env(varName) {
|
|
272
|
+
return new ArgBuilder({
|
|
273
|
+
...this.schema,
|
|
274
|
+
envVar: varName
|
|
275
|
+
});
|
|
276
|
+
}
|
|
277
|
+
/**
|
|
278
|
+
* Human-readable description shown in help output.
|
|
279
|
+
*
|
|
280
|
+
* @param description - Text displayed next to the arg in `--help`.
|
|
281
|
+
* @returns The builder (for chaining).
|
|
282
|
+
*
|
|
283
|
+
* @example
|
|
284
|
+
* ```ts
|
|
285
|
+
* arg.string().describe('Deploy target')
|
|
286
|
+
*
|
|
287
|
+
* // Help output:
|
|
288
|
+
* // Arguments:
|
|
289
|
+
* // <target> Deploy target
|
|
290
|
+
* ```
|
|
291
|
+
*/
|
|
292
|
+
describe(description) {
|
|
293
|
+
return new ArgBuilder({
|
|
294
|
+
...this.schema,
|
|
295
|
+
description
|
|
296
|
+
});
|
|
297
|
+
}
|
|
298
|
+
/**
|
|
299
|
+
* Mark this arg as deprecated.
|
|
300
|
+
*
|
|
301
|
+
* When used, a warning is emitted to stderr. Help text shows
|
|
302
|
+
* `[deprecated]` or `[deprecated: <reason>]`.
|
|
303
|
+
*
|
|
304
|
+
* Does not change the arg's type-level config — it's metadata only.
|
|
305
|
+
*
|
|
306
|
+
* @param message - Optional migration reason/guidance.
|
|
307
|
+
* @returns The builder (for chaining).
|
|
308
|
+
*
|
|
309
|
+
* @example
|
|
310
|
+
* ```ts
|
|
311
|
+
* arg.string().deprecated() // generic
|
|
312
|
+
* arg.string().deprecated('use --target flag instead') // with guidance
|
|
313
|
+
*
|
|
314
|
+
* // Help output:
|
|
315
|
+
* // Arguments:
|
|
316
|
+
* // <target> Deploy target [deprecated: use --target flag instead]
|
|
317
|
+
* ```
|
|
318
|
+
*/
|
|
319
|
+
deprecated(message) {
|
|
320
|
+
return new ArgBuilder({
|
|
321
|
+
...this.schema,
|
|
322
|
+
deprecated: message ?? true
|
|
323
|
+
});
|
|
324
|
+
}
|
|
325
|
+
/**
|
|
326
|
+
* Require an integer value. Composes with other numeric constraints.
|
|
327
|
+
*
|
|
328
|
+
* @param value - Whether to require an integer.
|
|
329
|
+
* @defaultValue `true`
|
|
330
|
+
* @returns The builder (for chaining).
|
|
331
|
+
*
|
|
332
|
+
* @example
|
|
333
|
+
* ```ts
|
|
334
|
+
* arg.number().int() // rejects 3.7, accepts 3
|
|
335
|
+
* arg.number({ int: true }).int(false) // re-allows non-integers
|
|
336
|
+
* ```
|
|
337
|
+
*/
|
|
338
|
+
int(value = true) {
|
|
339
|
+
return new ArgBuilder({
|
|
340
|
+
...this.schema,
|
|
341
|
+
numberConstraints: {
|
|
342
|
+
...this.schema.numberConstraints,
|
|
343
|
+
int: value
|
|
344
|
+
}
|
|
345
|
+
});
|
|
346
|
+
}
|
|
347
|
+
/**
|
|
348
|
+
* Set an inclusive lower bound. Composes with other numeric constraints;
|
|
349
|
+
* a later call overrides an earlier `min` (including one from the options
|
|
350
|
+
* object).
|
|
351
|
+
*
|
|
352
|
+
* @param value - Inclusive minimum.
|
|
353
|
+
* @returns The builder (for chaining).
|
|
354
|
+
*
|
|
355
|
+
* @example
|
|
356
|
+
* ```ts
|
|
357
|
+
* arg.number().min(0) // rejects -1, accepts 0
|
|
358
|
+
* arg.number({ min: 0 }).min(5) // effective min is 5
|
|
359
|
+
* ```
|
|
360
|
+
*/
|
|
361
|
+
min(value) {
|
|
362
|
+
const numberConstraints = {
|
|
363
|
+
...this.schema.numberConstraints,
|
|
364
|
+
min: value
|
|
365
|
+
};
|
|
366
|
+
assertNumberConstraints(numberConstraints);
|
|
367
|
+
return new ArgBuilder({
|
|
368
|
+
...this.schema,
|
|
369
|
+
numberConstraints
|
|
370
|
+
});
|
|
371
|
+
}
|
|
372
|
+
/**
|
|
373
|
+
* Set an inclusive upper bound. Composes with other numeric constraints;
|
|
374
|
+
* a later call overrides an earlier `max`.
|
|
375
|
+
*
|
|
376
|
+
* @param value - Inclusive maximum.
|
|
377
|
+
* @returns The builder (for chaining).
|
|
378
|
+
*
|
|
379
|
+
* @example
|
|
380
|
+
* ```ts
|
|
381
|
+
* arg.number().max(100) // rejects 101, accepts 100
|
|
382
|
+
* ```
|
|
383
|
+
*/
|
|
384
|
+
max(value) {
|
|
385
|
+
const numberConstraints = {
|
|
386
|
+
...this.schema.numberConstraints,
|
|
387
|
+
max: value
|
|
388
|
+
};
|
|
389
|
+
assertNumberConstraints(numberConstraints);
|
|
390
|
+
return new ArgBuilder({
|
|
391
|
+
...this.schema,
|
|
392
|
+
numberConstraints
|
|
393
|
+
});
|
|
394
|
+
}
|
|
395
|
+
/**
|
|
396
|
+
* Require (or, with `false`, allow) a finite value. Finiteness is enforced
|
|
397
|
+
* by default, so this is mainly used as `.finite(false)` to re-allow
|
|
398
|
+
* `Infinity` / `-Infinity`.
|
|
399
|
+
*
|
|
400
|
+
* @param allow - Whether to require a finite value.
|
|
401
|
+
* @defaultValue `true`
|
|
402
|
+
* @returns The builder (for chaining).
|
|
403
|
+
*
|
|
404
|
+
* @example
|
|
405
|
+
* ```ts
|
|
406
|
+
* arg.number().finite(false) // accepts Infinity
|
|
407
|
+
* ```
|
|
408
|
+
*/
|
|
409
|
+
finite(allow = true) {
|
|
410
|
+
return new ArgBuilder({
|
|
411
|
+
...this.schema,
|
|
412
|
+
numberConstraints: {
|
|
413
|
+
...this.schema.numberConstraints,
|
|
414
|
+
finite: allow
|
|
415
|
+
}
|
|
416
|
+
});
|
|
417
|
+
}
|
|
418
|
+
};
|
|
419
|
+
/**
|
|
420
|
+
* Positional argument schema factory.
|
|
421
|
+
*
|
|
422
|
+
* Entry point for defining args on a command. Use `arg.<kind>()` to create
|
|
423
|
+
* an {@linkcode ArgBuilder}, then chain modifiers and pass the result to
|
|
424
|
+
* `command().arg(name, builder)`.
|
|
425
|
+
*
|
|
426
|
+
* Four kinds are available:
|
|
427
|
+
* - `arg.string()` — raw string (most common)
|
|
428
|
+
* - `arg.number()` — parsed to number, errors on NaN
|
|
429
|
+
* - `arg.enum(values)` — constrained to listed literals
|
|
430
|
+
* - `arg.custom(fn)` — arbitrary parse function, infers return type
|
|
431
|
+
*
|
|
432
|
+
* @example
|
|
433
|
+
* ```ts
|
|
434
|
+
* import { command, arg } from '@kjanat/dreamcli';
|
|
435
|
+
*
|
|
436
|
+
* command('deploy')
|
|
437
|
+
* .arg('target', arg.string().env('DEPLOY_TARGET').describe('Where to deploy'))
|
|
438
|
+
* .arg('port', arg.number().env('PORT').default(3000))
|
|
439
|
+
* .action(({ args }) => {
|
|
440
|
+
* console.log(`Deploying to ${args.target} on port ${args.port}`);
|
|
441
|
+
* });
|
|
442
|
+
*
|
|
443
|
+
* // $ mycli deploy production 8080 → target='production', port=8080
|
|
444
|
+
* // $ DEPLOY_TARGET=staging mycli deploy → target='staging', port=3000
|
|
445
|
+
* ```
|
|
446
|
+
*/
|
|
447
|
+
const arg = {
|
|
448
|
+
string() {
|
|
449
|
+
return new ArgBuilder(createArgSchema("string"));
|
|
450
|
+
},
|
|
451
|
+
number(constraints) {
|
|
452
|
+
if (constraints !== void 0) assertNumberConstraints(constraints);
|
|
453
|
+
return new ArgBuilder(createArgSchema("number", constraints !== void 0 ? { numberConstraints: constraints } : {}));
|
|
454
|
+
},
|
|
455
|
+
enum(values) {
|
|
456
|
+
return new ArgBuilder(createArgSchema("enum", { enumValues: values }));
|
|
457
|
+
},
|
|
458
|
+
custom(parseFn) {
|
|
459
|
+
return new ArgBuilder(createArgSchema("custom", { parseFn }));
|
|
460
|
+
}
|
|
461
|
+
};
|
|
462
|
+
//#endregion
|
|
463
|
+
export { ArgBuilder, arg, createArgSchema };
|
|
@@ -4,6 +4,7 @@ import { PromptConfig } from "./prompt.mjs";
|
|
|
4
4
|
import { FlagBuilder, FlagConfig, FlagSchema, InferFlags } from "./flag.mjs";
|
|
5
5
|
import { ErasedMiddlewareHandler, Middleware } from "./middleware.mjs";
|
|
6
6
|
import { RunOptions, RunResult } from "./run.mjs";
|
|
7
|
+
import { Colors } from "ansispeck";
|
|
7
8
|
|
|
8
9
|
//#region src/core/schema/command.d.ts
|
|
9
10
|
/**
|
|
@@ -152,6 +153,23 @@ interface Out {
|
|
|
152
153
|
* decorative output should be suppressed regardless of `isTTY`.
|
|
153
154
|
*/
|
|
154
155
|
readonly isTTY: boolean;
|
|
156
|
+
/**
|
|
157
|
+
* Context-aware ANSI color palette (powered by `ansispeck`).
|
|
158
|
+
*
|
|
159
|
+
* Colors are enabled only when stdout is a TTY, JSON mode is off, and the
|
|
160
|
+
* environment supports color (`NO_COLOR`, `FORCE_COLOR`, `--no-color`,
|
|
161
|
+
* `--color`, `CI` are respected). When disabled, every formatter is an
|
|
162
|
+
* identity function — `out.color.red('x')` returns `'x'` — so handlers can
|
|
163
|
+
* style unconditionally without gating on `isTTY`/`jsonMode` themselves.
|
|
164
|
+
*
|
|
165
|
+
* @example
|
|
166
|
+
* ```ts
|
|
167
|
+
* .action(({ out }) => {
|
|
168
|
+
* out.log(`${out.color.green('✔')} deployed ${out.color.bold('api')}`);
|
|
169
|
+
* });
|
|
170
|
+
* ```
|
|
171
|
+
*/
|
|
172
|
+
readonly color: Colors;
|
|
155
173
|
/**
|
|
156
174
|
* Render tabular data.
|
|
157
175
|
*
|