@kjanat/dreamcli 3.0.0-rc.17 → 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,25 @@ 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
+
10
29
  ## [3.0.0-rc.17] - 2026-07-20
11
30
 
12
31
  ### Added
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 } : {},
@@ -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 {
@@ -160,6 +160,7 @@ async function prepareRuntimePreflight(options) {
160
160
  jsonMode,
161
161
  verbosity: hasQuietFlag ? "quiet" : options.options?.verbosity ?? "normal",
162
162
  stat: options.options?.stat ?? options.adapter.stat,
163
+ mkdir: options.options?.mkdir ?? options.adapter.mkdir,
163
164
  ...stdinData !== void 0 ? { stdinData } : {},
164
165
  ...options.options?.prompter !== void 0 ? { prompter: options.options.prompter } : autoPrompter !== void 0 ? { prompter: autoPrompter } : {},
165
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
  },
@@ -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));
@@ -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.17";
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 = "58d3353";
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.17",
3
+ "version": "3.0.0-rc.18",
4
4
  "description": "Schema-first, fully typed TypeScript CLI framework",
5
5
  "keywords": [
6
6
  "dreamcli",