@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 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.16...HEAD
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)" width="700" height="400" alt="dreamcli-migrate-dark" srcset="https://github.com/user-attachments/assets/1ef7f20c-9ffb-4cb6-a6bc-fb562895aa6f">
96
- <source media="(prefers-color-scheme: light)" width="700" height="400" alt="dreamcli-migrate-light" srcset="https://github.com/user-attachments/assets/1ee5f38d-cad8-47ec-94b2-c826eabab76b">
97
- <img alt="DreamCLI migration progress demo" width="700" height="400" src="https://github.com/user-attachments/assets/1ee5f38d-cad8-47ec-94b2-c826eabab76b">
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
@@ -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
- ...options?.verbosity !== void 0 ? { verbosity: options.verbosity } : {},
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: options?.verbosity ?? "normal"
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.includes("--json") ? head.filter((arg) => arg !== "--json") : 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.includes("--json") || options.options?.jsonMode === true;
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) return new ValidationError(`Path '${value}' for flag --${flagName} does not exist`, {
145
- code: "CONSTRAINT_VIOLATED",
146
- details: {
147
- flag: flagName,
148
- value,
149
- constraint: "mustExist"
150
- },
151
- suggest: `Provide an existing path for --${flagName}`
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 PathFlagOptions {
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' | 'directory';
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'`). */
@@ -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
  };
@@ -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.
@@ -113,6 +113,7 @@ function createDenoAdapter(ns) {
113
113
  exit: (code) => d.exit(code),
114
114
  readFile,
115
115
  stat,
116
+ mkdir: (path) => d.mkdir(path, { recursive: true }),
116
117
  homedir,
117
118
  configDir
118
119
  };
@@ -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.16";
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 = "561f448";
5
+ const DREAMCLI_REVISION = "ab6ffa5";
6
6
  //#endregion
7
7
  export { DREAMCLI_REVISION, DREAMCLI_VERSION };
@@ -227,6 +227,9 @@
227
227
  "file",
228
228
  "directory"
229
229
  ]
230
+ },
231
+ "create": {
232
+ "type": "boolean"
230
233
  }
231
234
  },
232
235
  "required": [
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kjanat/dreamcli",
3
- "version": "3.0.0-rc.16",
3
+ "version": "3.0.0-rc.18",
4
4
  "description": "Schema-first, fully typed TypeScript CLI framework",
5
5
  "keywords": [
6
6
  "dreamcli",