@kjanat/dreamcli 3.0.0-rc.18 → 3.0.0-rc.19

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,31 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [3.0.0-rc.19] - 2026-07-21
11
+
12
+ ### Added
13
+
14
+ - **Expanded config discovery** (#61) — the default search now covers three
15
+ scopes, first match wins, no merging:
16
+ 1. **Project**: the base directory (default `cwd`) and every ancestor up
17
+ to the filesystem root, nearest first, each probed for
18
+ `.{appName}.{ext}`, `{appName}.config.{ext}`, and the new
19
+ `.config/{appName}.{ext}` convention.
20
+ 2. **User**: XDG / AppData as before, plus
21
+ `~/Library/Application Support/{appName}/config.{ext}` on macOS.
22
+ 3. **System**: `/etc/{appName}/config.{ext}` on Linux and macOS.
23
+ - **`baseDir` discovery option** — `discoverConfig()` accepts a base
24
+ directory to anchor the project-scope walk somewhere other than `cwd`.
25
+ - **`RuntimeAdapter.userConfigDirs` / `systemConfigDirs`** — optional
26
+ ordered config roots supplied by the runtime adapters; discovery falls
27
+ back to `[configDir]` / `[]` when a custom adapter omits them.
28
+
29
+ ### Changed
30
+
31
+ - **Breaking**: `buildConfigSearchPaths(appName, options)` replaces the
32
+ positional `(appName, cwd, configDir, loaders?)` signature; options carry
33
+ `baseDir`, `userConfigDirs`, `systemConfigDirs`, and `loaders`.
34
+
10
35
  ## [3.0.0-rc.18] - 2026-07-21
11
36
 
12
37
  ### Added
@@ -497,12 +497,16 @@ declare class CLIBuilder {
497
497
  /**
498
498
  * Enable automatic config file discovery.
499
499
  *
500
- * When enabled, `.run()` probes standard paths before dispatching:
501
- * 1. `$CWD/.{appName}.json`
502
- * 2. `$CWD/{appName}.config.json`
503
- * 3. `$CONFIG_DIR/{appName}/config.json`
504
- * (`$XDG_CONFIG_HOME` / `~/.config` on Unix,
500
+ * When enabled, `.run()` probes standard paths before dispatching,
501
+ * first match wins, no merging:
502
+ * 1. Project scope — for `$CWD` and each ancestor directory up to the
503
+ * filesystem root, nearest first:
504
+ * `.{appName}.json`, `{appName}.config.json`, `.config/{appName}.json`
505
+ * 2. User scope — `{dir}/{appName}/config.json` for each user config
506
+ * root (`$XDG_CONFIG_HOME` / `~/.config` on Unix, plus
507
+ * `~/Library/Application Support` on macOS,
505
508
  * `%APPDATA%` / `%USERPROFILE%\\AppData\\Roaming` on Windows)
509
+ * 3. System scope — `/etc/{appName}/config.json` on Linux and macOS
506
510
  *
507
511
  * The user can override the path via `--config <path>` or `--config=<path>`.
508
512
  *
@@ -314,12 +314,16 @@ var CLIBuilder = class CLIBuilder {
314
314
  /**
315
315
  * Enable automatic config file discovery.
316
316
  *
317
- * When enabled, `.run()` probes standard paths before dispatching:
318
- * 1. `$CWD/.{appName}.json`
319
- * 2. `$CWD/{appName}.config.json`
320
- * 3. `$CONFIG_DIR/{appName}/config.json`
321
- * (`$XDG_CONFIG_HOME` / `~/.config` on Unix,
317
+ * When enabled, `.run()` probes standard paths before dispatching,
318
+ * first match wins, no merging:
319
+ * 1. Project scope — for `$CWD` and each ancestor directory up to the
320
+ * filesystem root, nearest first:
321
+ * `.{appName}.json`, `{appName}.config.json`, `.config/{appName}.json`
322
+ * 2. User scope — `{dir}/{appName}/config.json` for each user config
323
+ * root (`$XDG_CONFIG_HOME` / `~/.config` on Unix, plus
324
+ * `~/Library/Application Support` on macOS,
322
325
  * `%APPDATA%` / `%USERPROFILE%\\AppData\\Roaming` on Windows)
326
+ * 3. System scope — `/etc/{appName}/config.json` on Linux and macOS
323
327
  *
324
328
  * The user can override the path via `--config <path>` or `--config=<path>`.
325
329
  *
@@ -41,6 +41,14 @@ interface ConfigDiscoveryOptions {
41
41
  * Probed in order; first found wins.
42
42
  */
43
43
  readonly searchPaths?: readonly string[];
44
+ /**
45
+ * Directory the project-scope ancestor walk starts from.
46
+ * Anchors discovery to a location other than the process working
47
+ * directory (e.g. the directory of a file an editor integration is
48
+ * operating on).
49
+ * @defaultValue `adapter.cwd`
50
+ */
51
+ readonly baseDir?: string;
44
52
  }
45
53
  /** Successful config discovery — file found and parsed. */
46
54
  interface ConfigFound {
@@ -60,6 +68,23 @@ interface ConfigNotFound {
60
68
  }
61
69
  /** Discriminated result of config discovery. */
62
70
  type ConfigDiscoveryResult = ConfigFound | ConfigNotFound;
71
+ /** Directory scopes feeding {@link buildConfigSearchPaths}. */
72
+ interface ConfigSearchPathOptions {
73
+ /** Directory the project-scope ancestor walk starts from. */
74
+ readonly baseDir: string;
75
+ /**
76
+ * User-scope config roots, highest priority first
77
+ * (XDG / AppData, plus `~/Library/Application Support` on macOS).
78
+ */
79
+ readonly userConfigDirs: readonly string[];
80
+ /**
81
+ * System-scope config roots (`/etc` on Linux and macOS).
82
+ * @defaultValue `[]`
83
+ */
84
+ readonly systemConfigDirs?: readonly string[];
85
+ /** Custom {@link FormatLoader}s whose extensions expand the search set. */
86
+ readonly loaders?: readonly FormatLoader[];
87
+ }
63
88
  /**
64
89
  * Build the default config search paths for an app.
65
90
  *
@@ -68,34 +93,40 @@ type ConfigDiscoveryResult = ConfigFound | ConfigNotFound;
68
93
  * manually. Exported for debugging, custom discovery flows, and help text.
69
94
  *
70
95
  * Search order (first match wins):
71
- * 1. `$CWD/.{appName}.json` — dotfile in project root
72
- * 2. `$CWD/{appName}.config.json` — explicit config in project root
73
- * 3. `$CONFIG_DIR/{appName}/config.json` — XDG / AppData standard
74
- * (`$XDG_CONFIG_HOME` / `~/.config` on Unix,
75
- * `%APPDATA%` / `%USERPROFILE%\\AppData\\Roaming` on Windows)
96
+ * 1. Project scope — for `baseDir` and each ancestor directory up to the
97
+ * filesystem root, nearest first:
98
+ * 1. `{dir}/.{appName}.json` — dotfile
99
+ * 2. `{dir}/{appName}.config.json` — explicit config
100
+ * 3. `{dir}/.config/{appName}.json` — project `.config/` convention
101
+ * 2. User scope — `{userConfigDir}/{appName}/config.json` for each entry of
102
+ * `userConfigDirs`, in order.
103
+ * 3. System scope — `{systemConfigDir}/{appName}/config.json` for each entry
104
+ * of `systemConfigDirs`, in order.
76
105
  *
77
106
  * When custom {@link ConfigDiscoveryOptions.loaders | loaders} are registered,
78
107
  * each path pattern is repeated per supported extension (JSON always first).
79
108
  *
80
109
  * @param appName - CLI application name used to derive config filenames.
81
- * @param cwd - Current working directory (project-root search location).
82
- * @param configDir - Platform config directory (XDG / AppData).
83
- * @param loaders - Optional custom {@link FormatLoader}s whose extensions expand the search set.
110
+ * @param options - Directory scopes and loaders (see {@link ConfigSearchPathOptions}).
84
111
  * @returns Ordered list of candidate config file paths (first match wins).
85
112
  *
86
113
  * @example
87
114
  * ```ts
88
- * const paths = buildConfigSearchPaths('mycli', '/repo', '/home/me/.config');
115
+ * const paths = buildConfigSearchPaths('mycli', {
116
+ * baseDir: '/repo/packages/app',
117
+ * userConfigDirs: ['/home/me/.config'],
118
+ * systemConfigDirs: ['/etc'],
119
+ * });
89
120
  * ```
90
121
  */
91
- declare function buildConfigSearchPaths(appName: string, cwd: string, configDir: string, loaders?: readonly FormatLoader[]): readonly string[];
122
+ declare function buildConfigSearchPaths(appName: string, options: ConfigSearchPathOptions): readonly string[];
92
123
  /**
93
124
  * The subset of {@link RuntimeAdapter} needed for config discovery.
94
125
  *
95
126
  * Exported so custom hosts and tests can type the minimal adapter required by
96
127
  * {@link discoverConfig} without depending on the full runtime adapter shape.
97
128
  */
98
- type ConfigAdapter = Pick<RuntimeAdapter, 'readFile' | 'cwd' | 'configDir'>;
129
+ type ConfigAdapter = Pick<RuntimeAdapter, 'readFile' | 'cwd' | 'configDir'> & Partial<Pick<RuntimeAdapter, 'userConfigDirs' | 'systemConfigDirs'>>;
99
130
  /**
100
131
  * Discover and load a config file.
101
132
  *
@@ -157,4 +188,4 @@ declare function discoverConfig(appName: string, adapter: ConfigAdapter, options
157
188
  */
158
189
  declare function configFormat(extensions: readonly string[], parse: (content: string) => unknown): FormatLoader;
159
190
  //#endregion
160
- export { type ConfigAdapter, type ConfigDiscoveryOptions, type ConfigDiscoveryResult, type ConfigFound, type ConfigNotFound, type FormatLoader, type ManifestDiscoveryOptions, type PackageJsonAdapter, type PackageJsonData, type PackageRepository, type PackageRepositoryUrlOptions, buildConfigSearchPaths, configFormat, discoverConfig, discoverManifest, discoverPackageJson, inferCliName, packageRepositoryUrl };
191
+ export { type ConfigAdapter, type ConfigDiscoveryOptions, type ConfigDiscoveryResult, type ConfigFound, type ConfigNotFound, type ConfigSearchPathOptions, type FormatLoader, type ManifestDiscoveryOptions, type PackageJsonAdapter, type PackageJsonData, type PackageRepository, type PackageRepositoryUrlOptions, buildConfigSearchPaths, configFormat, discoverConfig, discoverManifest, discoverPackageJson, inferCliName, packageRepositoryUrl };
@@ -39,7 +39,31 @@ const jsonLoader = {
39
39
  */
40
40
  function joinPath(base, ...segments) {
41
41
  const sep = base.includes("\\") ? "\\" : "/";
42
- return [base, ...segments].join(sep);
42
+ return [base.endsWith(sep) ? base.slice(0, -1) : base, ...segments].join(sep);
43
+ }
44
+ /**
45
+ * List a directory and every ancestor up to the filesystem root,
46
+ * nearest first. Separator is inferred from the input; POSIX (`/`) and
47
+ * Windows drive roots (`C:\`) both terminate the walk.
48
+ *
49
+ * @internal
50
+ */
51
+ function ancestorDirs(base) {
52
+ const sep = base.includes("\\") ? "\\" : "/";
53
+ let current = base;
54
+ while (current.length > 1 && current.endsWith(sep) && !current.endsWith(`:${sep}`)) current = current.slice(0, -1);
55
+ const dirs = [current];
56
+ while (true) {
57
+ const idx = current.lastIndexOf(sep);
58
+ if (idx < 0) break;
59
+ let parent = current.slice(0, idx);
60
+ if (parent === "") parent = sep;
61
+ else if (/^[A-Za-z]:$/.test(parent)) parent = `${parent}${sep}`;
62
+ if (parent === current) break;
63
+ dirs.push(parent);
64
+ current = parent;
65
+ }
66
+ return dirs;
43
67
  }
44
68
  /**
45
69
  * Extract the file extension (without leading dot, lowercased).
@@ -60,32 +84,42 @@ function getExtension(path) {
60
84
  * manually. Exported for debugging, custom discovery flows, and help text.
61
85
  *
62
86
  * Search order (first match wins):
63
- * 1. `$CWD/.{appName}.json` — dotfile in project root
64
- * 2. `$CWD/{appName}.config.json` — explicit config in project root
65
- * 3. `$CONFIG_DIR/{appName}/config.json` — XDG / AppData standard
66
- * (`$XDG_CONFIG_HOME` / `~/.config` on Unix,
67
- * `%APPDATA%` / `%USERPROFILE%\\AppData\\Roaming` on Windows)
87
+ * 1. Project scope — for `baseDir` and each ancestor directory up to the
88
+ * filesystem root, nearest first:
89
+ * 1. `{dir}/.{appName}.json` — dotfile
90
+ * 2. `{dir}/{appName}.config.json` — explicit config
91
+ * 3. `{dir}/.config/{appName}.json` — project `.config/` convention
92
+ * 2. User scope — `{userConfigDir}/{appName}/config.json` for each entry of
93
+ * `userConfigDirs`, in order.
94
+ * 3. System scope — `{systemConfigDir}/{appName}/config.json` for each entry
95
+ * of `systemConfigDirs`, in order.
68
96
  *
69
97
  * When custom {@link ConfigDiscoveryOptions.loaders | loaders} are registered,
70
98
  * each path pattern is repeated per supported extension (JSON always first).
71
99
  *
72
100
  * @param appName - CLI application name used to derive config filenames.
73
- * @param cwd - Current working directory (project-root search location).
74
- * @param configDir - Platform config directory (XDG / AppData).
75
- * @param loaders - Optional custom {@link FormatLoader}s whose extensions expand the search set.
101
+ * @param options - Directory scopes and loaders (see {@link ConfigSearchPathOptions}).
76
102
  * @returns Ordered list of candidate config file paths (first match wins).
77
103
  *
78
104
  * @example
79
105
  * ```ts
80
- * const paths = buildConfigSearchPaths('mycli', '/repo', '/home/me/.config');
106
+ * const paths = buildConfigSearchPaths('mycli', {
107
+ * baseDir: '/repo/packages/app',
108
+ * userConfigDirs: ['/home/me/.config'],
109
+ * systemConfigDirs: ['/etc'],
110
+ * });
81
111
  * ```
82
112
  */
83
- function buildConfigSearchPaths(appName, cwd, configDir, loaders) {
84
- const extensions = buildExtensionList(loaders);
113
+ function buildConfigSearchPaths(appName, options) {
114
+ const extensions = buildExtensionList(options.loaders);
85
115
  const paths = [];
86
- for (const ext of extensions) paths.push(joinPath(cwd, `.${appName}.${ext}`));
87
- for (const ext of extensions) paths.push(joinPath(cwd, `${appName}.config.${ext}`));
88
- for (const ext of extensions) paths.push(joinPath(configDir, appName, `config.${ext}`));
116
+ for (const dir of ancestorDirs(options.baseDir)) {
117
+ for (const ext of extensions) paths.push(joinPath(dir, `.${appName}.${ext}`));
118
+ for (const ext of extensions) paths.push(joinPath(dir, `${appName}.config.${ext}`));
119
+ for (const ext of extensions) paths.push(joinPath(dir, ".config", `${appName}.${ext}`));
120
+ }
121
+ for (const dir of options.userConfigDirs) for (const ext of extensions) paths.push(joinPath(dir, appName, `config.${ext}`));
122
+ for (const dir of options.systemConfigDirs ?? []) for (const ext of extensions) paths.push(joinPath(dir, appName, `config.${ext}`));
89
123
  return paths;
90
124
  }
91
125
  /**
@@ -158,7 +192,12 @@ function buildLoaderMap(loaders) {
158
192
  */
159
193
  async function discoverConfig(appName, adapter, options) {
160
194
  const loaderMap = buildLoaderMap(options?.loaders);
161
- const searchPaths = options?.configPath !== void 0 ? [options.configPath] : options?.searchPaths ?? buildConfigSearchPaths(appName, adapter.cwd, adapter.configDir, options?.loaders);
195
+ const searchPaths = options?.configPath !== void 0 ? [options.configPath] : options?.searchPaths ?? buildConfigSearchPaths(appName, {
196
+ baseDir: options?.baseDir ?? adapter.cwd,
197
+ userConfigDirs: adapter.userConfigDirs ?? [adapter.configDir],
198
+ systemConfigDirs: adapter.systemConfigDirs ?? [],
199
+ ...options?.loaders !== void 0 ? { loaders: options.loaders } : {}
200
+ });
162
201
  for (const candidatePath of searchPaths) {
163
202
  const content = await adapter.readFile(candidatePath);
164
203
  if (content === null) {
@@ -116,6 +116,21 @@ interface RuntimeAdapter {
116
116
  * Config discovery appends the app-specific subdirectory.
117
117
  */
118
118
  readonly configDir: string;
119
+ /**
120
+ * User-scope config roots for discovery, highest priority first.
121
+ *
122
+ * - Unix: `[configDir]`
123
+ * - macOS: `[configDir, ~/Library/Application Support]`
124
+ * - Windows: `[configDir]`
125
+ *
126
+ * When absent, discovery falls back to `[configDir]`.
127
+ */
128
+ readonly userConfigDirs?: readonly string[];
129
+ /**
130
+ * System-scope config roots for discovery (`['/etc']` on Linux and
131
+ * macOS, `[]` on Windows). When absent, discovery probes none.
132
+ */
133
+ readonly systemConfigDirs?: readonly string[];
119
134
  }
120
135
  /** Current terminal dimensions in columns and rows. */
121
136
  interface TerminalSize {
@@ -212,6 +227,10 @@ interface TestAdapterOptions {
212
227
  readonly homedir?: string;
213
228
  /** Config directory (defaults to `'/home/test/.config'`). */
214
229
  readonly configDir?: string;
230
+ /** User-scope config roots for discovery (defaults to `[configDir]`). */
231
+ readonly userConfigDirs?: readonly string[];
232
+ /** System-scope config roots for discovery (defaults to `[]`). */
233
+ readonly systemConfigDirs?: readonly string[];
215
234
  }
216
235
  /**
217
236
  * Error thrown by adapter implementations that model process exit as an
@@ -83,7 +83,9 @@ function createTestAdapter(options) {
83
83
  stat: options?.stat ?? noopStat,
84
84
  mkdir: options?.mkdir ?? noopMkdir,
85
85
  homedir: options?.homedir ?? "/home/test",
86
- configDir: options?.configDir ?? "/home/test/.config"
86
+ configDir: options?.configDir ?? "/home/test/.config",
87
+ userConfigDirs: options?.userConfigDirs ?? [options?.configDir ?? "/home/test/.config"],
88
+ systemConfigDirs: options?.systemConfigDirs ?? []
87
89
  };
88
90
  }
89
91
  //#endregion
@@ -115,7 +115,9 @@ function createDenoAdapter(ns) {
115
115
  stat,
116
116
  mkdir: (path) => d.mkdir(path, { recursive: true }),
117
117
  homedir,
118
- configDir
118
+ configDir,
119
+ userConfigDirs: d.build.os === "darwin" ? [configDir, `${homedir}/Library/Application Support`] : [configDir],
120
+ systemConfigDirs: d.build.os === "windows" ? [] : ["/etc"]
119
121
  };
120
122
  }
121
123
  /** Normalize terminal dimensions and discard unusable values. @internal */
@@ -104,6 +104,8 @@ function createNodeAdapter(proc) {
104
104
  };
105
105
  const homedir = resolveHomedir(p.env, p.platform);
106
106
  const configDir = resolveConfigDir(p.env, p.platform, homedir);
107
+ const userConfigDirs = p.platform === "darwin" ? [configDir, `${homedir}/Library/Application Support`] : [configDir];
108
+ const systemConfigDirs = p.platform === "win32" ? [] : ["/etc"];
107
109
  const stdinIsTTY = p.stdin.isTTY === true;
108
110
  return {
109
111
  argv: p.argv,
@@ -122,7 +124,9 @@ function createNodeAdapter(proc) {
122
124
  stat,
123
125
  mkdir,
124
126
  homedir,
125
- configDir
127
+ configDir,
128
+ userConfigDirs,
129
+ systemConfigDirs
126
130
  };
127
131
  }
128
132
  /** Normalize terminal dimensions and discard unusable values. @internal */
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.18";
3
+ const DREAMCLI_VERSION = "3.0.0-rc.19";
4
4
  /** Git short SHA (e.g. `"f9b5f1a"`). `"dev"` when running unbundled. */
5
- const DREAMCLI_REVISION = "ab6ffa5";
5
+ const DREAMCLI_REVISION = "349859e";
6
6
  //#endregion
7
7
  export { DREAMCLI_REVISION, DREAMCLI_VERSION };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kjanat/dreamcli",
3
- "version": "3.0.0-rc.18",
3
+ "version": "3.0.0-rc.19",
4
4
  "description": "Schema-first, fully typed TypeScript CLI framework",
5
5
  "keywords": [
6
6
  "dreamcli",