@kjanat/dreamcli 3.0.0-rc.16 → 3.0.0-rc.18
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 +41 -1
- package/README.md +3 -3
- package/dist/core/cli/index.mjs +5 -2
- package/dist/core/cli/planner.mjs +7 -1
- package/dist/core/cli/root-help.mjs +4 -0
- package/dist/core/cli/runtime-preflight.d.mts +4 -0
- package/dist/core/cli/runtime-preflight.mjs +5 -3
- package/dist/core/execution/index.mjs +2 -1
- package/dist/core/json-schema/index.mjs +4 -2
- package/dist/core/output/contracts.d.mts +1 -1
- package/dist/core/output/contracts.mjs +1 -1
- package/dist/core/output/index.d.mts +5 -0
- package/dist/core/output/index.mjs +8 -0
- package/dist/core/resolve/contracts.d.mts +5 -0
- package/dist/core/resolve/flags.d.mts +3 -1
- package/dist/core/resolve/flags.mjs +29 -12
- package/dist/core/resolve/index.mjs +1 -1
- package/dist/core/schema/command.d.mts +7 -0
- package/dist/core/schema/flag.d.mts +38 -6
- package/dist/core/schema/flag.mjs +2 -1
- package/dist/core/schema/run.d.mts +7 -0
- package/dist/runtime/adapter.d.mts +14 -0
- package/dist/runtime/adapter.mjs +3 -0
- package/dist/runtime/deno.d.mts +4 -0
- package/dist/runtime/deno.mjs +1 -0
- package/dist/runtime/node.mjs +4 -0
- package/dist/version.mjs +2 -2
- package/dreamcli.schema.json +3 -0
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,45 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [3.0.0-rc.18] - 2026-07-21
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- **`flag.path({ type: 'directory', create: true })`** — creates the directory
|
|
15
|
+
(recursively) at resolution time when nothing exists at the path. Only
|
|
16
|
+
available with `type: 'directory'`, enforced at the type level. Creation
|
|
17
|
+
runs through a new `mkdir` seam: `RuntimeAdapter.mkdir`, overridable via
|
|
18
|
+
run options, noop in the test adapter, so `src/core` stays process-free.
|
|
19
|
+
|
|
20
|
+
### Fixed
|
|
21
|
+
|
|
22
|
+
- **`flag.path({ type, mustExist: false })` rejected missing paths** — the
|
|
23
|
+
builder recorded the explicit `mustExist: false`, but resolution errored on
|
|
24
|
+
any missing path whenever path checks were active, making an optional
|
|
25
|
+
to-be-created path (e.g. an `--outdir` that the command itself creates)
|
|
26
|
+
impossible to declare. A missing path now passes when `mustExist` is
|
|
27
|
+
`false`; an existing path is still type-checked.
|
|
28
|
+
|
|
29
|
+
## [3.0.0-rc.17] - 2026-07-20
|
|
30
|
+
|
|
31
|
+
### Added
|
|
32
|
+
|
|
33
|
+
- **`out.status()`** — a success/status line channel that writes to **stderr**
|
|
34
|
+
(stdout stays clean for piping) and is suppressed under quiet verbosity.
|
|
35
|
+
`info` remains stdout-bound; `warn`/`error` remain always-emitted.
|
|
36
|
+
- **Global `--quiet`/`-q` flag** — sets quiet verbosity on every CLI, wired
|
|
37
|
+
like `--json`: detected and stripped at the root before dispatch (command
|
|
38
|
+
schemas never see it), honoring the `--` separator so a literal `-q`
|
|
39
|
+
positional reaches the command unchanged. Listed under root help's
|
|
40
|
+
`Global options:`.
|
|
41
|
+
|
|
42
|
+
### Fixed
|
|
43
|
+
|
|
44
|
+
- **`.run()` misread a post-separator `--json`** — runtime preflight used a
|
|
45
|
+
naive `includes('--json')`, so `mycli cmd -- --json` entered JSON mode via
|
|
46
|
+
the adapter path even though `.execute()` correctly treats it as a
|
|
47
|
+
positional. Preflight now uses the `--`-aware detection.
|
|
48
|
+
|
|
10
49
|
## [3.0.0-rc.16] - 2026-07-20
|
|
11
50
|
|
|
12
51
|
### Added
|
|
@@ -1315,7 +1354,8 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
|
1315
1354
|
- MIT License.
|
|
1316
1355
|
- Markdownlint configuration.
|
|
1317
1356
|
|
|
1318
|
-
[Unreleased]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.
|
|
1357
|
+
[Unreleased]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.17...HEAD
|
|
1358
|
+
[3.0.0-rc.17]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.16...v3.0.0-rc.17
|
|
1319
1359
|
[3.0.0-rc.16]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.15...v3.0.0-rc.16
|
|
1320
1360
|
[3.0.0-rc.15]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.14...v3.0.0-rc.15
|
|
1321
1361
|
[3.0.0-rc.14]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.13...v3.0.0-rc.14
|
package/README.md
CHANGED
|
@@ -92,9 +92,9 @@ cli('greet').default(greet).run();
|
|
|
92
92
|
### Multi-command CLI
|
|
93
93
|
|
|
94
94
|
<picture>
|
|
95
|
-
<source media="(prefers-color-scheme: dark)"
|
|
96
|
-
<source media="(prefers-color-scheme: light)"
|
|
97
|
-
<img alt="DreamCLI migration progress demo" width="700"
|
|
95
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://github.com/user-attachments/assets/1ef7f20c-9ffb-4cb6-a6bc-fb562895aa6f">
|
|
96
|
+
<source media="(prefers-color-scheme: light)" srcset="https://github.com/user-attachments/assets/1ee5f38d-cad8-47ec-94b2-c826eabab76b">
|
|
97
|
+
<img alt="DreamCLI migration progress demo" width="700" src="https://github.com/user-attachments/assets/1ee5f38d-cad8-47ec-94b2-c826eabab76b">
|
|
98
98
|
</picture>
|
|
99
99
|
|
|
100
100
|
```ts
|
package/dist/core/cli/index.mjs
CHANGED
|
@@ -170,6 +170,7 @@ function buildCommandRunOptions(options, helpOptions, meta) {
|
|
|
170
170
|
...options?.prompter !== void 0 ? { prompter: options.prompter } : {},
|
|
171
171
|
...options?.answers !== void 0 ? { answers: options.answers } : {},
|
|
172
172
|
...options?.stat !== void 0 ? { stat: options.stat } : {},
|
|
173
|
+
...options?.mkdir !== void 0 ? { mkdir: options.mkdir } : {},
|
|
173
174
|
...options?.verbosity !== void 0 ? { verbosity: options.verbosity } : {},
|
|
174
175
|
...options?.jsonMode !== void 0 ? { jsonMode: options.jsonMode } : {},
|
|
175
176
|
...options?.isTTY !== void 0 ? { isTTY: options.isTTY } : {},
|
|
@@ -584,8 +585,9 @@ var CLIBuilder = class CLIBuilder {
|
|
|
584
585
|
*/
|
|
585
586
|
async execute(argv, options) {
|
|
586
587
|
const jsonMode = includesBeforeSeparator(argv, "--json") || options?.jsonMode === true;
|
|
588
|
+
const verbosity = includesBeforeSeparator(argv, "--quiet") || includesBeforeSeparator(argv, "-q") ? "quiet" : options?.verbosity;
|
|
587
589
|
const captureOptions = {
|
|
588
|
-
...
|
|
590
|
+
...verbosity !== void 0 ? { verbosity } : {},
|
|
589
591
|
...jsonMode ? { jsonMode } : {},
|
|
590
592
|
...options?.isTTY !== void 0 ? { isTTY: options.isTTY } : {},
|
|
591
593
|
...hyperlinksOption(resolveHyperlinkOverride(options?.env ?? {}, argv))
|
|
@@ -615,12 +617,13 @@ var CLIBuilder = class CLIBuilder {
|
|
|
615
617
|
...options,
|
|
616
618
|
plugins: this.schema.plugins,
|
|
617
619
|
...jsonMode ? { jsonMode } : {},
|
|
620
|
+
...verbosity !== void 0 ? { verbosity } : {},
|
|
618
621
|
...flagSettings !== void 0 ? { flags: flagSettings } : {}
|
|
619
622
|
};
|
|
620
623
|
const output = {
|
|
621
624
|
jsonMode,
|
|
622
625
|
isTTY: out.isTTY,
|
|
623
|
-
verbosity:
|
|
626
|
+
verbosity: verbosity ?? "normal"
|
|
624
627
|
};
|
|
625
628
|
const planned = planInvocation({
|
|
626
629
|
schema: options?.flags !== void 0 ? {
|
|
@@ -190,6 +190,12 @@ function planCompletionsFlag(argv, config) {
|
|
|
190
190
|
};
|
|
191
191
|
}
|
|
192
192
|
}
|
|
193
|
+
/** Root-level output flags stripped before dispatch (never part of a command schema). */
|
|
194
|
+
const ROOT_OUTPUT_FLAGS = /* @__PURE__ */ new Set([
|
|
195
|
+
"--json",
|
|
196
|
+
"--quiet",
|
|
197
|
+
"-q"
|
|
198
|
+
]);
|
|
193
199
|
/**
|
|
194
200
|
* Decide what to do with an argv invocation before any command executes.
|
|
195
201
|
*
|
|
@@ -202,7 +208,7 @@ function planInvocation(options) {
|
|
|
202
208
|
const separatorIndex = options.argv.indexOf("--");
|
|
203
209
|
const head = separatorIndex === -1 ? options.argv : options.argv.slice(0, separatorIndex);
|
|
204
210
|
const tail = separatorIndex === -1 ? [] : options.argv.slice(separatorIndex);
|
|
205
|
-
const filteredHead = head.
|
|
211
|
+
const filteredHead = head.some((arg) => ROOT_OUTPUT_FLAGS.has(arg)) ? head.filter((arg) => !ROOT_OUTPUT_FLAGS.has(arg)) : head;
|
|
206
212
|
const filteredArgv = separatorIndex === -1 ? filteredHead : [...filteredHead, ...tail];
|
|
207
213
|
const defaultCommand = options.schema.defaultCommand;
|
|
208
214
|
const rootValueFlags = defaultCommand !== void 0 ? buildFlagLookup(defaultCommand.schema.flags, options.schema.flagSettings) : void 0;
|
|
@@ -202,6 +202,10 @@ function formatGlobalOptionsSection(schema, width, theme) {
|
|
|
202
202
|
left: theme.flag("--json"),
|
|
203
203
|
description: "Emit machine-readable JSON output"
|
|
204
204
|
});
|
|
205
|
+
entries.push({
|
|
206
|
+
left: theme.flag("-q, --quiet"),
|
|
207
|
+
description: "Suppress informational output"
|
|
208
|
+
});
|
|
205
209
|
if (schema.configSettings !== void 0) entries.push({
|
|
206
210
|
left: `${theme.flag("--config")} ${theme.placeholder("<path>")}`,
|
|
207
211
|
description: "Load configuration from the given file"
|
|
@@ -114,6 +114,8 @@ interface RuntimePreflightOptions {
|
|
|
114
114
|
readonly isTTY?: boolean;
|
|
115
115
|
/** Filesystem probe override for `flag.path()` checks; bypasses the adapter probe. */
|
|
116
116
|
readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
|
|
117
|
+
/** Directory creation override for `flag.path()` `create` checks; bypasses the adapter. */
|
|
118
|
+
readonly mkdir?: (path: string) => Promise<void>;
|
|
117
119
|
}
|
|
118
120
|
/**
|
|
119
121
|
* Fully resolved runtime inputs ready for the execution pipeline.
|
|
@@ -139,6 +141,8 @@ interface RuntimeExecutionInputs {
|
|
|
139
141
|
readonly config?: Readonly<Record<string, unknown>>;
|
|
140
142
|
/** Filesystem probe (from the adapter) for `flag.path()` checks. */
|
|
141
143
|
readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
|
|
144
|
+
/** Directory creation (from the adapter) for `flag.path()` `create` checks. */
|
|
145
|
+
readonly mkdir?: (path: string) => Promise<void>;
|
|
142
146
|
}
|
|
143
147
|
/** Preflight succeeded — all runtime inputs are resolved and ready for execution. @internal */
|
|
144
148
|
interface ReadyRuntimePreflight {
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { CLIError, ParseError } from "../errors/index.mjs";
|
|
2
|
-
import { parse } from "../parse/index.mjs";
|
|
2
|
+
import { includesBeforeSeparator, parse } from "../parse/index.mjs";
|
|
3
3
|
import { createTerminalPrompter } from "../prompt/index.mjs";
|
|
4
4
|
import { discoverManifest, inferCliName } from "../config/package-json.mjs";
|
|
5
5
|
import { deriveHelpLinks } from "./help-links.mjs";
|
|
@@ -138,7 +138,8 @@ async function prepareRuntimePreflight(options) {
|
|
|
138
138
|
configPath: void 0,
|
|
139
139
|
filteredArgv: rawArgv
|
|
140
140
|
};
|
|
141
|
-
const jsonMode = filteredArgv
|
|
141
|
+
const jsonMode = includesBeforeSeparator(filteredArgv, "--json") || options.options?.jsonMode === true;
|
|
142
|
+
const hasQuietFlag = includesBeforeSeparator(filteredArgv, "--quiet") || includesBeforeSeparator(filteredArgv, "-q");
|
|
142
143
|
const isCompletions = isCompletionsInvocation(options.schema, filteredArgv);
|
|
143
144
|
const schema = await applyPackageJsonDiscovery(options.schema, options.adapter, options.inheritedName, isCompletions);
|
|
144
145
|
const loadedConfig = await loadRuntimeConfig(schema, options.adapter, configPath, isCompletions, options.options?.config);
|
|
@@ -157,8 +158,9 @@ async function prepareRuntimePreflight(options) {
|
|
|
157
158
|
env: options.options?.env ?? options.adapter.env,
|
|
158
159
|
isTTY: options.options?.isTTY ?? options.adapter.isTTY,
|
|
159
160
|
jsonMode,
|
|
160
|
-
verbosity: options.options?.verbosity ?? "normal",
|
|
161
|
+
verbosity: hasQuietFlag ? "quiet" : options.options?.verbosity ?? "normal",
|
|
161
162
|
stat: options.options?.stat ?? options.adapter.stat,
|
|
163
|
+
mkdir: options.options?.mkdir ?? options.adapter.mkdir,
|
|
162
164
|
...stdinData !== void 0 ? { stdinData } : {},
|
|
163
165
|
...options.options?.prompter !== void 0 ? { prompter: options.options.prompter } : autoPrompter !== void 0 ? { prompter: autoPrompter } : {},
|
|
164
166
|
...loadedConfig !== void 0 ? { config: loadedConfig } : {}
|
|
@@ -63,7 +63,8 @@ async function executeCommand(request) {
|
|
|
63
63
|
...options?.env !== void 0 ? { env: options.env } : {},
|
|
64
64
|
...options?.config !== void 0 ? { config: options.config } : {},
|
|
65
65
|
...effectivePrompter !== void 0 ? { prompter: effectivePrompter } : {},
|
|
66
|
-
...options?.stat !== void 0 ? { stat: options.stat } : {}
|
|
66
|
+
...options?.stat !== void 0 ? { stat: options.stat } : {},
|
|
67
|
+
...options?.mkdir !== void 0 ? { mkdir: options.mkdir } : {}
|
|
67
68
|
});
|
|
68
69
|
const resolvedParams = {
|
|
69
70
|
args: resolved.args,
|
|
@@ -137,7 +137,8 @@ function serializeFlag(schema, opts) {
|
|
|
137
137
|
if (schema.unique) result.unique = true;
|
|
138
138
|
if (schema.pathChecks !== void 0) result.pathChecks = {
|
|
139
139
|
mustExist: schema.pathChecks.mustExist,
|
|
140
|
-
...schema.pathChecks.type !== void 0 ? { type: schema.pathChecks.type } : {}
|
|
140
|
+
...schema.pathChecks.type !== void 0 ? { type: schema.pathChecks.type } : {},
|
|
141
|
+
...schema.pathChecks.create ? { create: true } : {}
|
|
141
142
|
};
|
|
142
143
|
if (schema.valueHint !== void 0) result.valueHint = schema.valueHint;
|
|
143
144
|
if (opts.includePrompts && schema.prompt !== void 0) result.prompt = serializePrompt(schema.prompt);
|
|
@@ -656,7 +657,8 @@ const definitionMetaSchema = withDefinitionMetaSchemaDescriptions({
|
|
|
656
657
|
additionalProperties: false,
|
|
657
658
|
properties: {
|
|
658
659
|
mustExist: { type: "boolean" },
|
|
659
|
-
type: { enum: ["file", "directory"] }
|
|
660
|
+
type: { enum: ["file", "directory"] },
|
|
661
|
+
create: { type: "boolean" }
|
|
660
662
|
},
|
|
661
663
|
required: ["mustExist"]
|
|
662
664
|
},
|
|
@@ -71,7 +71,7 @@ declare const outputContract: {
|
|
|
71
71
|
declare function resolveOutputPolicy(options: ResolveOutputPolicyOptions): OutputPolicy;
|
|
72
72
|
/** Resolve the default text stream for non-JSON structured output. */
|
|
73
73
|
declare function resolveTextStream(policy: OutputPolicy): OutputStream;
|
|
74
|
-
/** Whether `info()` messages should be emitted under the current policy. */
|
|
74
|
+
/** Whether `info()`/`status()` messages should be emitted under the current policy. */
|
|
75
75
|
declare function shouldEmitInfo(policy: OutputPolicy): boolean;
|
|
76
76
|
/** Resolve the concrete table format under the current policy. */
|
|
77
77
|
declare function resolveTableFormat(policy: OutputPolicy, options?: TableOptions): 'text' | 'json';
|
|
@@ -11,7 +11,7 @@ function resolveOutputPolicy(options) {
|
|
|
11
11
|
function resolveTextStream(policy) {
|
|
12
12
|
return policy.jsonMode ? "stderr" : "stdout";
|
|
13
13
|
}
|
|
14
|
-
/** Whether `info()` messages should be emitted under the current policy. */
|
|
14
|
+
/** Whether `info()`/`status()` messages should be emitted under the current policy. */
|
|
15
15
|
function shouldEmitInfo(policy) {
|
|
16
16
|
return policy.verbosity !== "quiet";
|
|
17
17
|
}
|
|
@@ -151,6 +151,11 @@ declare class OutputChannel implements Out {
|
|
|
151
151
|
* In JSON mode, redirected to stderr.
|
|
152
152
|
*/
|
|
153
153
|
info(message: string): void;
|
|
154
|
+
/**
|
|
155
|
+
* Status line to stderr (stdout stays clean for piping).
|
|
156
|
+
* Suppressed when verbosity is `'quiet'`.
|
|
157
|
+
*/
|
|
158
|
+
status(message: string): void;
|
|
154
159
|
/** Warning to stderr. Always emitted. */
|
|
155
160
|
warn(message: string): void;
|
|
156
161
|
/** Error to stderr. Always emitted. */
|
|
@@ -138,6 +138,14 @@ var OutputChannel = class {
|
|
|
138
138
|
if (!shouldEmitInfo(this.policy)) return;
|
|
139
139
|
writeLine(resolveWriterForStream(this.options, resolveTextStream(this.policy)), message);
|
|
140
140
|
}
|
|
141
|
+
/**
|
|
142
|
+
* Status line to stderr (stdout stays clean for piping).
|
|
143
|
+
* Suppressed when verbosity is `'quiet'`.
|
|
144
|
+
*/
|
|
145
|
+
status(message) {
|
|
146
|
+
if (!shouldEmitInfo(this.policy)) return;
|
|
147
|
+
writeLine(this.options.stderr, message);
|
|
148
|
+
}
|
|
141
149
|
/** Warning to stderr. Always emitted. */
|
|
142
150
|
warn(message) {
|
|
143
151
|
writeLine(this.options.stderr, message);
|
|
@@ -53,6 +53,11 @@ interface ResolveOptions {
|
|
|
53
53
|
* `null` when nothing does. When absent, path checks are skipped.
|
|
54
54
|
*/
|
|
55
55
|
readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
|
|
56
|
+
/**
|
|
57
|
+
* Recursive directory creation for `flag.path()` `create` checks. When
|
|
58
|
+
* absent, missing paths are not created and existence rules apply as-is.
|
|
59
|
+
*/
|
|
60
|
+
readonly mkdir?: (path: string) => Promise<void>;
|
|
56
61
|
}
|
|
57
62
|
/** Structured deprecation notice emitted for explicitly sourced values. */
|
|
58
63
|
interface DeprecationWarning {
|
|
@@ -10,8 +10,10 @@ import { ErasedInteractiveResolver } from "../schema/command.mjs";
|
|
|
10
10
|
* Returns what exists at the path, or `null` when nothing does.
|
|
11
11
|
*/
|
|
12
12
|
type StatFn = (path: string) => Promise<'file' | 'directory' | null>;
|
|
13
|
+
/** Recursive directory creation injected by the caller for `flag.path()` `create` checks. */
|
|
14
|
+
type MkdirFn = (path: string) => Promise<void>;
|
|
13
15
|
/** Walk every declared flag through the resolution chain (cli -> env -> config -> prompt -> default), collecting deprecations and throwing aggregated errors. */
|
|
14
|
-
declare function resolveFlags(flagSchemas: Readonly<Record<string, FlagSchema>>, parsedFlags: Readonly<Record<string, unknown>>, env: Readonly<Record<string, string | undefined>>, config: Readonly<Record<string, unknown>>, prompter: PromptEngine | undefined, interactive: ErasedInteractiveResolver | undefined, deprecations: DeprecationWarning[], stat: StatFn | undefined): Promise<Readonly<Record<string, unknown>>>;
|
|
16
|
+
declare function resolveFlags(flagSchemas: Readonly<Record<string, FlagSchema>>, parsedFlags: Readonly<Record<string, unknown>>, env: Readonly<Record<string, string | undefined>>, config: Readonly<Record<string, unknown>>, prompter: PromptEngine | undefined, interactive: ErasedInteractiveResolver | undefined, deprecations: DeprecationWarning[], stat: StatFn | undefined, mkdir: MkdirFn | undefined): Promise<Readonly<Record<string, unknown>>>;
|
|
15
17
|
/** Maps each flag kind to the prompt kinds that produce compatible values. */
|
|
16
18
|
declare const COMPATIBLE_PROMPT_KINDS: Record<FlagKind, readonly PromptKind[]>;
|
|
17
19
|
//#endregion
|
|
@@ -11,7 +11,7 @@ import { resolveConfigPath } from "./config.mjs";
|
|
|
11
11
|
* @internal
|
|
12
12
|
*/
|
|
13
13
|
/** Walk every declared flag through the resolution chain (cli -> env -> config -> prompt -> default), collecting deprecations and throwing aggregated errors. */
|
|
14
|
-
async function resolveFlags(flagSchemas, parsedFlags, env, config, prompter, interactive, deprecations, stat) {
|
|
14
|
+
async function resolveFlags(flagSchemas, parsedFlags, env, config, prompter, interactive, deprecations, stat, mkdir) {
|
|
15
15
|
const resolved = {};
|
|
16
16
|
const errors = [];
|
|
17
17
|
const hardErrorFlags = /* @__PURE__ */ new Set();
|
|
@@ -125,7 +125,7 @@ async function resolveFlags(flagSchemas, parsedFlags, env, config, prompter, int
|
|
|
125
125
|
const value = resolved[name];
|
|
126
126
|
if (schema.kind === "array" && schema.unique && Array.isArray(value)) resolved[name] = [...new Set(value)];
|
|
127
127
|
if (schema.pathChecks !== void 0 && typeof value === "string" && stat !== void 0) {
|
|
128
|
-
const violation = await validatePathChecks(name, value, schema.pathChecks, stat);
|
|
128
|
+
const violation = await validatePathChecks(name, value, schema.pathChecks, stat, mkdir);
|
|
129
129
|
if (violation !== void 0) errors.push(violation);
|
|
130
130
|
}
|
|
131
131
|
}
|
|
@@ -139,17 +139,34 @@ async function resolveFlags(flagSchemas, parsedFlags, env, config, prompter, int
|
|
|
139
139
|
* {@link ValidationError} with code `'CONSTRAINT_VIOLATED'` otherwise.
|
|
140
140
|
* @internal
|
|
141
141
|
*/
|
|
142
|
-
async function validatePathChecks(flagName, value, checks, stat) {
|
|
142
|
+
async function validatePathChecks(flagName, value, checks, stat, mkdir) {
|
|
143
143
|
const found = await stat(value);
|
|
144
|
-
if (found === null)
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
144
|
+
if (found === null) {
|
|
145
|
+
if (checks.create && mkdir !== void 0) try {
|
|
146
|
+
await mkdir(value);
|
|
147
|
+
return;
|
|
148
|
+
} catch (error) {
|
|
149
|
+
return new ValidationError(`Failed to create directory '${value}' for flag --${flagName}: ${error instanceof Error ? error.message : String(error)}`, {
|
|
150
|
+
code: "CONSTRAINT_VIOLATED",
|
|
151
|
+
details: {
|
|
152
|
+
flag: flagName,
|
|
153
|
+
value,
|
|
154
|
+
constraint: "create"
|
|
155
|
+
},
|
|
156
|
+
suggest: `Provide a creatable or existing directory path for --${flagName}`
|
|
157
|
+
});
|
|
158
|
+
}
|
|
159
|
+
if (!checks.mustExist) return void 0;
|
|
160
|
+
return new ValidationError(`Path '${value}' for flag --${flagName} does not exist`, {
|
|
161
|
+
code: "CONSTRAINT_VIOLATED",
|
|
162
|
+
details: {
|
|
163
|
+
flag: flagName,
|
|
164
|
+
value,
|
|
165
|
+
constraint: "mustExist"
|
|
166
|
+
},
|
|
167
|
+
suggest: `Provide an existing path for --${flagName}`
|
|
168
|
+
});
|
|
169
|
+
}
|
|
153
170
|
if (checks.type !== void 0 && found !== checks.type) return new ValidationError(`Path '${value}' for flag --${flagName} is a ${found}, expected a ${checks.type}`, {
|
|
154
171
|
code: "CONSTRAINT_VIOLATED",
|
|
155
172
|
details: {
|
|
@@ -64,7 +64,7 @@ async function resolve(schema, parsed, options) {
|
|
|
64
64
|
let args = {};
|
|
65
65
|
const errors = [];
|
|
66
66
|
try {
|
|
67
|
-
flags = await resolveFlags(schema.flags, parsed.flags, env, config, prompter, schema.interactive, deprecations, options?.stat);
|
|
67
|
+
flags = await resolveFlags(schema.flags, parsed.flags, env, config, prompter, schema.interactive, deprecations, options?.stat, options?.mkdir);
|
|
68
68
|
} catch (error) {
|
|
69
69
|
if (!isValidationError(error)) throw error;
|
|
70
70
|
errors.push(...collectValidationErrors(error));
|
|
@@ -112,6 +112,13 @@ interface Out {
|
|
|
112
112
|
log(message: string): void;
|
|
113
113
|
/** Informational (may be suppressed in quiet mode). */
|
|
114
114
|
info(message: string): void;
|
|
115
|
+
/**
|
|
116
|
+
* Status line to stderr, suppressed in quiet mode.
|
|
117
|
+
*
|
|
118
|
+
* Keeps stdout clean for piping; for success and progress notes like
|
|
119
|
+
* `Wrote <path>` that scripts silence with `--quiet`.
|
|
120
|
+
*/
|
|
121
|
+
status(message: string): void;
|
|
115
122
|
/** Warning to stderr. */
|
|
116
123
|
warn(message: string): void;
|
|
117
124
|
/** Error to stderr. */
|
|
@@ -123,19 +123,45 @@ type FlagKind = (typeof FLAG_KINDS)[number];
|
|
|
123
123
|
* value from config files. Narrow inside the function as needed.
|
|
124
124
|
*/
|
|
125
125
|
type FlagParseFn<T> = (raw: unknown) => T;
|
|
126
|
-
/** Options accepted by `flag.path()
|
|
127
|
-
interface
|
|
126
|
+
/** Options accepted by `flag.path()` for any-kind or file paths. */
|
|
127
|
+
interface FilePathFlagOptions {
|
|
128
128
|
/**
|
|
129
129
|
* Reject the value if nothing exists at the path.
|
|
130
130
|
* @defaultValue `false` (`true` when `type` is set)
|
|
131
131
|
*/
|
|
132
132
|
readonly mustExist?: boolean;
|
|
133
133
|
/**
|
|
134
|
-
* Require the path to be a file or a directory. Implies existence
|
|
134
|
+
* Require the path to be a file or a directory. Implies existence
|
|
135
|
+
* unless `mustExist` is explicitly `false`, in which case a missing
|
|
136
|
+
* path passes and only an existing path is type-checked.
|
|
135
137
|
* @defaultValue `undefined` (any kind)
|
|
136
138
|
*/
|
|
137
|
-
readonly type?: 'file'
|
|
139
|
+
readonly type?: 'file';
|
|
140
|
+
/** Directory creation is only available with `type: 'directory'`. */
|
|
141
|
+
readonly create?: never;
|
|
138
142
|
}
|
|
143
|
+
/** Options accepted by `flag.path()` for directory paths. */
|
|
144
|
+
interface DirectoryPathFlagOptions {
|
|
145
|
+
/**
|
|
146
|
+
* Reject the value if nothing exists at the path.
|
|
147
|
+
* @defaultValue `false` (`true` when `type` is set)
|
|
148
|
+
*/
|
|
149
|
+
readonly mustExist?: boolean;
|
|
150
|
+
/**
|
|
151
|
+
* Require the path to be a directory. Implies existence unless
|
|
152
|
+
* `mustExist` is explicitly `false`, in which case a missing path
|
|
153
|
+
* passes and only an existing path is type-checked.
|
|
154
|
+
*/
|
|
155
|
+
readonly type: 'directory';
|
|
156
|
+
/**
|
|
157
|
+
* Create the directory (recursively) when nothing exists at the path.
|
|
158
|
+
* An existing non-directory path still fails the type check.
|
|
159
|
+
* @defaultValue `false`
|
|
160
|
+
*/
|
|
161
|
+
readonly create?: boolean;
|
|
162
|
+
}
|
|
163
|
+
/** Options accepted by `flag.path()`. */
|
|
164
|
+
type PathFlagOptions = FilePathFlagOptions | DirectoryPathFlagOptions;
|
|
139
165
|
/**
|
|
140
166
|
* Filesystem expectations attached by `flag.path()`.
|
|
141
167
|
*
|
|
@@ -148,9 +174,11 @@ interface PathChecks {
|
|
|
148
174
|
readonly mustExist: boolean;
|
|
149
175
|
/**
|
|
150
176
|
* Require the existing path to be a file or a directory. Implies
|
|
151
|
-
* existence when set
|
|
177
|
+
* existence when set, unless `mustExist` is `false`.
|
|
152
178
|
*/
|
|
153
179
|
readonly type: 'file' | 'directory' | undefined;
|
|
180
|
+
/** Create the directory (recursively) when nothing exists at the path. */
|
|
181
|
+
readonly create: boolean;
|
|
154
182
|
}
|
|
155
183
|
/** Runtime descriptor for a flag alias. */
|
|
156
184
|
interface FlagAlias {
|
|
@@ -975,7 +1003,7 @@ interface FlagFactory {
|
|
|
975
1003
|
* env, and config values are validated identically.
|
|
976
1004
|
*
|
|
977
1005
|
* @param options - Optional existence/type checks. `type` implies
|
|
978
|
-
* existence
|
|
1006
|
+
* existence unless `mustExist` is explicitly `false`.
|
|
979
1007
|
* @returns A {@link FlagBuilder} for path strings.
|
|
980
1008
|
*
|
|
981
1009
|
* @example
|
|
@@ -983,6 +1011,10 @@ interface FlagFactory {
|
|
|
983
1011
|
* flag.path() // any string, help shows <path>
|
|
984
1012
|
* flag.path({ mustExist: true }) // rejects missing paths
|
|
985
1013
|
* flag.path({ type: 'directory' }) // must exist and be a directory
|
|
1014
|
+
* flag.path({ type: 'directory', mustExist: false })
|
|
1015
|
+
* // missing passes; existing must be a directory
|
|
1016
|
+
* flag.path({ type: 'directory', create: true })
|
|
1017
|
+
* // created recursively when missing
|
|
986
1018
|
* ```
|
|
987
1019
|
*/
|
|
988
1020
|
path(options?: PathFlagOptions): FlagBuilder<{
|
|
@@ -671,7 +671,8 @@ const flag = {
|
|
|
671
671
|
return new FlagBuilder(createSchema("string", {
|
|
672
672
|
pathChecks: options?.mustExist === true || options?.type !== void 0 ? {
|
|
673
673
|
mustExist: options.mustExist ?? true,
|
|
674
|
-
type: options.type
|
|
674
|
+
type: options.type,
|
|
675
|
+
create: options.type === "directory" && options.create === true
|
|
675
676
|
} : void 0,
|
|
676
677
|
valueHint: "path"
|
|
677
678
|
}));
|
|
@@ -68,6 +68,13 @@ interface RunOptions {
|
|
|
68
68
|
* override), path checks are skipped.
|
|
69
69
|
*/
|
|
70
70
|
readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
|
|
71
|
+
/**
|
|
72
|
+
* Recursive directory creation for `flag.path()` `create` checks.
|
|
73
|
+
*
|
|
74
|
+
* `CLIBuilder.run()` supplies the runtime adapter's implementation
|
|
75
|
+
* automatically. When absent, missing paths are not created.
|
|
76
|
+
*/
|
|
77
|
+
readonly mkdir?: (path: string) => Promise<void>;
|
|
71
78
|
/**
|
|
72
79
|
* Verbosity level for the output channel.
|
|
73
80
|
* @defaultValue `'normal'`
|
|
@@ -91,6 +91,15 @@ interface RuntimeAdapter {
|
|
|
91
91
|
* Used by `flag.path()` existence/type checks after resolution.
|
|
92
92
|
*/
|
|
93
93
|
readonly stat: (path: string) => Promise<'file' | 'directory' | null>;
|
|
94
|
+
/**
|
|
95
|
+
* Create a directory, including missing parents.
|
|
96
|
+
*
|
|
97
|
+
* Succeeds when the directory already exists. Throws on other I/O errors
|
|
98
|
+
* (permission denied, existing file at the path, etc.).
|
|
99
|
+
*
|
|
100
|
+
* Used by `flag.path()` `create` checks after resolution.
|
|
101
|
+
*/
|
|
102
|
+
readonly mkdir: (path: string) => Promise<void>;
|
|
94
103
|
/**
|
|
95
104
|
* User home directory (absolute path).
|
|
96
105
|
*
|
|
@@ -194,6 +203,11 @@ interface TestAdapterOptions {
|
|
|
194
203
|
* ```
|
|
195
204
|
*/
|
|
196
205
|
readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
|
|
206
|
+
/**
|
|
207
|
+
* Directory creation stub for `flag.path()` `create` checks (defaults to
|
|
208
|
+
* a noop that resolves without creating anything).
|
|
209
|
+
*/
|
|
210
|
+
readonly mkdir?: (path: string) => Promise<void>;
|
|
197
211
|
/** Home directory (defaults to `'/home/test'`). */
|
|
198
212
|
readonly homedir?: string;
|
|
199
213
|
/** Config directory (defaults to `'/home/test/.config'`). */
|
package/dist/runtime/adapter.mjs
CHANGED
|
@@ -34,6 +34,8 @@ const eofRead = () => Promise.resolve(null);
|
|
|
34
34
|
const noopReadFile = () => Promise.resolve(null);
|
|
35
35
|
/** Noop stat — reports `null` (nothing exists) for all paths. */
|
|
36
36
|
const noopStat = () => Promise.resolve(null);
|
|
37
|
+
/** Noop mkdir — resolves without creating anything. */
|
|
38
|
+
const noopMkdir = () => Promise.resolve();
|
|
37
39
|
/**
|
|
38
40
|
* Create a test runtime adapter with injectable process state.
|
|
39
41
|
*
|
|
@@ -79,6 +81,7 @@ function createTestAdapter(options) {
|
|
|
79
81
|
}),
|
|
80
82
|
readFile: options?.readFile ?? noopReadFile,
|
|
81
83
|
stat: options?.stat ?? noopStat,
|
|
84
|
+
mkdir: options?.mkdir ?? noopMkdir,
|
|
82
85
|
homedir: options?.homedir ?? "/home/test",
|
|
83
86
|
configDir: options?.configDir ?? "/home/test/.config"
|
|
84
87
|
};
|
package/dist/runtime/deno.d.mts
CHANGED
|
@@ -66,6 +66,10 @@ interface DenoNamespace {
|
|
|
66
66
|
stat(path: string): Promise<{
|
|
67
67
|
readonly isDirectory: boolean;
|
|
68
68
|
}>;
|
|
69
|
+
/** Create a directory (requires `--allow-write`). */
|
|
70
|
+
mkdir(path: string, options?: {
|
|
71
|
+
readonly recursive?: boolean;
|
|
72
|
+
}): Promise<void>;
|
|
69
73
|
}
|
|
70
74
|
/**
|
|
71
75
|
* Create a runtime adapter backed by the Deno namespace.
|
package/dist/runtime/deno.mjs
CHANGED
package/dist/runtime/node.mjs
CHANGED
|
@@ -99,6 +99,9 @@ function createNodeAdapter(proc) {
|
|
|
99
99
|
throw err;
|
|
100
100
|
}
|
|
101
101
|
};
|
|
102
|
+
const mkdir = async (path) => {
|
|
103
|
+
await (await import("node:fs/promises")).mkdir(path, { recursive: true });
|
|
104
|
+
};
|
|
102
105
|
const homedir = resolveHomedir(p.env, p.platform);
|
|
103
106
|
const configDir = resolveConfigDir(p.env, p.platform, homedir);
|
|
104
107
|
const stdinIsTTY = p.stdin.isTTY === true;
|
|
@@ -117,6 +120,7 @@ function createNodeAdapter(proc) {
|
|
|
117
120
|
exit: (code) => p.exit(code),
|
|
118
121
|
readFile,
|
|
119
122
|
stat,
|
|
123
|
+
mkdir,
|
|
120
124
|
homedir,
|
|
121
125
|
configDir
|
|
122
126
|
};
|
package/dist/version.mjs
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
//#region src/version.ts
|
|
2
2
|
/** Package version (e.g. `"0.9.1"`). `"dev"` when running unbundled. */
|
|
3
|
-
const DREAMCLI_VERSION = "3.0.0-rc.
|
|
3
|
+
const DREAMCLI_VERSION = "3.0.0-rc.18";
|
|
4
4
|
/** Git short SHA (e.g. `"f9b5f1a"`). `"dev"` when running unbundled. */
|
|
5
|
-
const DREAMCLI_REVISION = "
|
|
5
|
+
const DREAMCLI_REVISION = "ab6ffa5";
|
|
6
6
|
//#endregion
|
|
7
7
|
export { DREAMCLI_REVISION, DREAMCLI_VERSION };
|
package/dreamcli.schema.json
CHANGED