@effected/xdg 0.1.0

package/AppDirs.js

@@ -0,0 +1,208 @@
+import { NativeDirs } from "./NativeDirs.js";
+import { CurrentPlatform, Xdg } from "./Xdg.js";
+import { Context, Effect, FileSystem, Layer, Option, Path, Schema } from "effect";
+
+//#region src/AppDirs.ts
+/**
+* The four directory kinds XDG separates, plus the runtime directory.
+*
+* @public
+*/
+const AppDirKind = Schema.Literals([
+	"config",
+	"data",
+	"cache",
+	"state",
+	"runtime"
+]);
+/**
+* Indicates that an application directory could not be created.
+*
+* @remarks
+* The only way `AppDirs` fails. Resolution cannot fail — it happens once, at
+* layer construction, from an environment that is already resolved — so this
+* error means exactly one thing: the `mkdir -p` did not work. `directory` says
+* which kind, `path` says where, and `cause` carries the underlying
+* `PlatformError` structurally. v3 carried `reason: String(e)` and a `directory`
+* that could also be the string `"all"`.
+*
+* @public
+*/
+var AppDirsError = class extends Schema.TaggedErrorClass()("AppDirsError", {
+	/** Which directory kind failed. */
+	directory: AppDirKind,
+	/** The path that could not be created. */
+	path: Schema.String,
+	/** The underlying failure, preserved structurally. */
+	cause: Schema.Defect()
+}) {
+	get message() {
+		return `Failed to create the ${this.directory} directory at "${this.path}"`;
+	}
+};
+/**
+* The fully resolved, app-namespaced directories.
+*
+* @public
+*/
+var ResolvedAppDirs = class extends Schema.Class("ResolvedAppDirs")({
+	/** The app's configuration directory. */
+	config: Schema.String,
+	/** The app's data directory. */
+	data: Schema.String,
+	/** The app's cache directory. */
+	cache: Schema.String,
+	/** The app's state directory. */
+	state: Schema.String,
+	/**
+	* The app's runtime directory.
+	*
+	* @remarks
+	* Absent unless `$XDG_RUNTIME_DIR` is set or `dirs.runtime` overrides it.
+	* There is no defensible fallback for a runtime directory — it must be
+	* user-owned, mode 0700 and cleaned on logout — so inventing one would be a
+	* lie, and the key is simply absent.
+	*/
+	runtime: Schema.optionalKey(Schema.String),
+	/**
+	* Where to **look** for configuration, in priority order.
+	*
+	* @remarks
+	* The app's own config directory, then each `$XDG_CONFIG_DIRS` entry
+	* namespaced. This is the half of the XDG spec v3 ignored entirely, and it is
+	* what makes {@link XdgConfig.resolver} a real search rather than a single stat.
+	*/
+	configSearchPath: Schema.Array(Schema.String),
+	/** Where to look for data files, in priority order. */
+	dataSearchPath: Schema.Array(Schema.String)
+}) {};
+/**
+* Resolve one directory kind through the five-level precedence.
+*
+* 1. an explicit `dirs.<kind>` override;
+* 2. the XDG environment variable, namespaced (`$XDG_CONFIG_HOME/<ns>`);
+* 3. the native directory, when `native: true` and the platform has one;
+* 4. `$HOME/<fallbackDir>` — all four kinds collapse to the one directory;
+* 5. `$HOME/.<namespace>`.
+*
+* Rungs 4 and 5 are deliberately **not** the XDG spec's per-kind defaults
+* (`~/.config`, `~/.local/share`, …). This is inherited v3 behaviour and is kept:
+* a CLI wanting spec defaults passes them as `dirs` overrides. The deviation is
+* documented rather than left for a reader to discover.
+*/
+const resolveDir = (input) => {
+	const { override, xdgHome, native, options, home, path } = input;
+	if (override !== void 0) return override;
+	if (xdgHome !== void 0) return path.join(xdgHome, options.namespace);
+	if (Option.isSome(native)) return native.value;
+	if (options.fallbackDir !== void 0) return path.join(home, options.fallbackDir);
+	return path.join(home, `.${options.namespace}`);
+};
+/** The app's own directory, then each system directory, namespaced. Nearest first. */
+const searchPath = (own, systemDirs, namespace, path) => [own, ...systemDirs.map((dir) => path.join(dir, namespace))];
+const resolveAll = (options, paths, platform, path) => {
+	const native = options.native ? NativeDirs.resolve({
+		platform,
+		namespace: options.namespace,
+		paths,
+		path
+	}) : Option.none();
+	const forKind = (xdgHome, nativeDir, override) => resolveDir({
+		override,
+		xdgHome,
+		native: Option.map(native, nativeDir),
+		options,
+		home: paths.home,
+		path
+	});
+	const config = forKind(paths.configHome, (n) => n.config, options.dirs?.config);
+	const data = forKind(paths.dataHome, (n) => n.data, options.dirs?.data);
+	const cache = forKind(paths.cacheHome, (n) => n.cache, options.dirs?.cache);
+	const state = forKind(paths.stateHome, (n) => n.state, options.dirs?.state);
+	const runtime = options.dirs?.runtime ?? (paths.runtimeDir !== void 0 ? path.join(paths.runtimeDir, options.namespace) : void 0);
+	return ResolvedAppDirs.make({
+		config,
+		data,
+		cache,
+		state,
+		...runtime !== void 0 && { runtime },
+		configSearchPath: searchPath(config, paths.configDirs, options.namespace, path),
+		dataSearchPath: searchPath(data, paths.dataDirs, options.namespace, path)
+	});
+};
+/**
+* A namespace is a single path component. Anything else escapes the app's own
+* directories, so it **dies** rather than resolving somewhere surprising. This
+* is wiring, not input: only code supplies a namespace, so a bad one is a
+* programmer error and belongs on the defect channel, not in `E`.
+*/
+const badNamespace = (namespace) => {
+	if (namespace.length === 0) return /* @__PURE__ */ new Error("AppDirs.layer: `namespace` must not be empty");
+	if (/[/\\]/.test(namespace) || namespace === "." || namespace === "..") return /* @__PURE__ */ new Error(`AppDirs.layer: \`namespace\` must be a single path component, received ${JSON.stringify(namespace)}`);
+};
+/**
+* App-namespaced XDG directories, with on-demand creation.
+*
+* @remarks
+* `AppDirs.layer` is a layer-**returning function**: calling it twice builds two
+* independent services. Bind its result to a const and provide that const, per
+* the layer memoization discipline.
+*
+* @example
+* ```ts
+* const AppDirsLayer = AppDirs.layer({ namespace: "myapp", native: true });
+* const XdgLayer = Layer.mergeAll(Xdg.layer, AppDirsLayer.pipe(Layer.provide(Xdg.layer)));
+* ```
+*
+* @public
+*/
+var AppDirs = class AppDirs extends Context.Service()("@effected/xdg/AppDirs") {
+	/**
+	* Resolve the namespace's directories against the ambient {@link Xdg}
+	* environment and platform.
+	*
+	* @remarks
+	* The error channel is `never`. The one failure that could happen during
+	* resolution — an unset `HOME` — surfaces on {@link Xdg.layer} as an
+	* `XdgEnvError`, before an `AppDirs` exists at all. v3 laundered it into an
+	* `AppDirsError({ directory: "all" })`.
+	*/
+	static layer(options) {
+		return Layer.effect(AppDirs, Effect.gen(function* () {
+			const invalid = badNamespace(options.namespace);
+			if (invalid !== void 0) return yield* Effect.die(invalid);
+			const paths = yield* Xdg;
+			const fs = yield* FileSystem.FileSystem;
+			const path = yield* Path.Path;
+			const platform = yield* CurrentPlatform;
+			const dirs = resolveAll(options, paths, platform, path);
+			const makeDir = (kind, target) => fs.makeDirectory(target, { recursive: true }).pipe(Effect.mapError((cause) => new AppDirsError({
+				directory: kind,
+				path: target,
+				cause
+			})), Effect.as(target));
+			const runtimeDir = dirs.runtime;
+			const ensureRuntime = (runtimeDir === void 0 ? Effect.succeed(Option.none()) : Effect.map(makeDir("runtime", runtimeDir), Option.some)).pipe(Effect.withSpan("AppDirs.ensureRuntime"));
+			return {
+				namespace: options.namespace,
+				dirs,
+				ensureConfig: makeDir("config", dirs.config).pipe(Effect.withSpan("AppDirs.ensureConfig")),
+				ensureData: makeDir("data", dirs.data).pipe(Effect.withSpan("AppDirs.ensureData")),
+				ensureCache: makeDir("cache", dirs.cache).pipe(Effect.withSpan("AppDirs.ensureCache")),
+				ensureState: makeDir("state", dirs.state).pipe(Effect.withSpan("AppDirs.ensureState")),
+				ensureRuntime,
+				ensure: Effect.gen(function* () {
+					yield* makeDir("config", dirs.config);
+					yield* makeDir("data", dirs.data);
+					yield* makeDir("cache", dirs.cache);
+					yield* makeDir("state", dirs.state);
+					if (dirs.runtime !== void 0) yield* makeDir("runtime", dirs.runtime);
+					return dirs;
+				}).pipe(Effect.withSpan("AppDirs.ensure"))
+			};
+		}));
+	}
+};
+
+//#endregion
+export { AppDirKind, AppDirs, AppDirsError, ResolvedAppDirs };

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NativeDirs.js

@@ -0,0 +1,71 @@
+import { Option, Schema } from "effect";
+
+//#region src/NativeDirs.ts
+/**
+* The OS-native application directories for one namespace.
+*
+* @remarks
+* On platforms without OS-level separation of these concerns, `config`, `data`
+* and `state` collapse to the same directory — `~/Library/Application Support/<ns>`
+* on macOS — while `cache` stays distinct.
+*
+* @public
+*/
+var NativeDirs = class NativeDirs extends Schema.Class("NativeDirs")({
+	/** Where configuration lives. */
+	config: Schema.String,
+	/** Where application data lives. */
+	data: Schema.String,
+	/** Where discardable cached data lives. */
+	cache: Schema.String,
+	/** Where persistent-but-regenerable state lives. */
+	state: Schema.String
+}) {
+	/**
+	* Map a platform and an environment onto the native directories for a namespace.
+	*
+	* @remarks
+	* **Pure**: no filesystem, no environment, no `process.platform`. Every input
+	* is a parameter, which is what makes the whole platform matrix testable
+	* without any platform IO. Paths are joined through the supplied `Path`, so a
+	* win32 `Path` layer yields win32 separators — v3 interpolated `/` on every
+	* platform.
+	*
+	* - **darwin** — `config`/`data`/`state` under `~/Library/Application Support/<ns>`;
+	*   `cache` under `~/Library/Caches/<ns>`.
+	* - **win32** — `config`/`data` under `%APPDATA%/<ns>`; `cache` under
+	*   `%LOCALAPPDATA%/<ns>/Cache`; `state` under `%LOCALAPPDATA%/<ns>`. When the
+	*   variables are unset, `%APPDATA%` falls back to `<home>/AppData/Roaming` and
+	*   `%LOCALAPPDATA%` to `<home>/AppData/Local`.
+	* - **everything else** — `Option.none()`. On Linux, XDG *is* the native
+	*   convention, so there is no override to apply; returning `none` rather than
+	*   a duplicate of the XDG answer is what lets a precedence ladder skip the
+	*   rung cleanly instead of shadowing the rung below it.
+	*/
+	static resolve(input) {
+		const { platform, namespace, paths, path } = input;
+		if (platform === "darwin") {
+			const appSupport = path.join(paths.home, "Library", "Application Support", namespace);
+			return Option.some(NativeDirs.make({
+				config: appSupport,
+				data: appSupport,
+				cache: path.join(paths.home, "Library", "Caches", namespace),
+				state: appSupport
+			}));
+		}
+		if (platform === "win32") {
+			const roaming = paths.appData ?? path.join(paths.home, "AppData", "Roaming");
+			const local = paths.localAppData ?? path.join(paths.home, "AppData", "Local");
+			return Option.some(NativeDirs.make({
+				config: path.join(roaming, namespace),
+				data: path.join(roaming, namespace),
+				cache: path.join(local, namespace, "Cache"),
+				state: path.join(local, namespace)
+			}));
+		}
+		return Option.none();
+	}
+};
+
+//#endregion
+export { NativeDirs };

package/README.md

@@ -0,0 +1,140 @@
+# @effected/xdg
+
+[![npm](https://img.shields.io/npm/v/@effected%2Fxdg?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/xdg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
+[![TypeScript 6.0](https://img.shields.io/badge/TypeScript-6.0-3178c6.svg)](https://www.typescriptlang.org/)
+
+XDG Base Directory resolution for Effect. `Xdg` reads the environment — `$HOME`, the four `*_HOME` variables, `$XDG_RUNTIME_DIR`, and the `$XDG_CONFIG_DIRS` / `$XDG_DATA_DIRS` search paths — once, at layer construction. `AppDirs` turns that into the config, data, cache, state and runtime directories for one application namespace, with on-demand creation. `NativeDirs` supplies the macOS and Windows conventions for applications that want them, and `XdgConfig` plugs the whole thing into [`@effected/config-file`](../config-file) as a resolver chain and a save target.
+
+> **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
+> development against a single pinned Effect v4 beta. Packages graduate to
+> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
+> exactly the ones the kit is built and tested against, install
+> [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
+>
+> **Stability: unstable.** This package's API surface is not yet considered
+> complete and may change across `0.x` releases. Pin an exact version — even a
+> package marked *stable* before `1.0.0` can introduce a breaking change by
+> accident, and an exact pin turns that into a type-check error rather than a
+> runtime surprise. Full policy: [release strategy](https://github.com/spencerbeggs/effected#release-strategy).
+
+## Why @effected/xdg
+
+Path resolution is not IO, and modeling it as IO poisons everything downstream. The environment is fixed for the life of a process, so this package reads it exactly once — when the layer is built — and the service's shape *is* the resolved value. `appDirs.dirs.config` is a `string`, not an `Effect<string, XdgEnvError>`. Reading a path cannot fail, cannot be observed to do IO and drops straight into config-file's `defaultPath` slot, which is typed `Effect<string, never, R>` and would otherwise need an `orDie` to satisfy.
+
+Two more things follow from taking the spec seriously. The system search paths are half of XDG and are usually skipped: a config lookup here probes the app's own config directory — whichever rung of the precedence below resolved it — *and then* each `$XDG_CONFIG_DIRS` entry, namespaced, and it absorbs failure per candidate — an unreadable `/etc/xdg` means "this candidate did not match", never "abort the search and hide the perfectly readable file below it". And the runtime directory has no fallback ladder, because there is no defensible one: it must be user-owned and mode 0700, so when `$XDG_RUNTIME_DIR` is unset the key is simply absent rather than pointing somewhere invented.
+
+## Install
+
+```bash
+npm install @effected/xdg effect @effect/platform-node
+```
+
+```bash
+pnpm add @effected/xdg effect @effect/platform-node
+```
+
+Requires Node.js >=24.11.0.
+
+`effect` v4 is a peer dependency, and so are `@effected/walker` (the upward-traversal and search primitives the resolvers are built on) and `@effected/config-file` (whose `ConfigResolver` seam `XdgConfig` implements). Package managers that install peers automatically will pull them in; add them to your manifest explicitly if yours does not. There are no runtime dependencies.
+
+Creating directories needs a `FileSystem` and a `Path` implementation, provided once at the edge — from `@effect/platform-node` on Node. Resolution itself needs neither.
+
+## Quick start
+
+Build `AppDirs` for your namespace, provide it the `Xdg` environment and the platform layers, and read the paths:
+
+```ts
+import { AppDirs, Xdg } from "@effected/xdg";
+import { NodeFileSystem, NodePath } from "@effect/platform-node";
+import { Effect, Layer } from "effect";
+
+const PlatformLive = Layer.mergeAll(NodeFileSystem.layer, NodePath.layer);
+
+const AppDirsLive = AppDirs.layer({ namespace: "myapp", native: true }).pipe(
+  Layer.provide(Layer.mergeAll(Xdg.layer, PlatformLive)),
+);
+
+const program = Effect.gen(function* () {
+  const appDirs = yield* AppDirs;
+  console.log(appDirs.dirs.config);
+  // Linux, XDG_CONFIG_HOME set:   $XDG_CONFIG_HOME/myapp
+  // Linux, XDG_CONFIG_HOME unset: $HOME/.myapp
+  // macOS with `native: true`:    $HOME/Library/Application Support/myapp
+  return yield* appDirs.ensureConfig;
+  // The same path, now created on disk.
+});
+
+Effect.runPromise(program.pipe(Effect.provide(AppDirsLive)));
+```
+
+`AppDirs.layer` is a layer-returning *function*, not a layer: calling it twice builds two independent services. Bind its result to a const, as above, and provide that const.
+
+## Precedence
+
+Each of `config`, `data`, `cache` and `state` resolves through five rungs, first match wins:
+
+1. an explicit `dirs.<kind>` override — an absolute path, and it wins outright;
+2. the XDG variable, namespaced: `$XDG_CONFIG_HOME/<namespace>`;
+3. the OS-native directory, when `native: true` and the platform has one;
+4. `$HOME/<fallbackDir>` — all four kinds collapse into that one directory;
+5. `$HOME/.<namespace>`.
+
+Rungs 4 and 5 are deliberately not the spec's per-kind defaults (`~/.config`, `~/.local/share`): an application that wants those passes them as `dirs` overrides. The runtime directory skips the ladder entirely — an override, or `$XDG_RUNTIME_DIR/<namespace>`, or nothing.
+
+`NativeDirs.resolve` is pure — platform, namespace, environment and `Path` all arrive as parameters — so the whole matrix is testable with no filesystem and no `process.platform` read. On macOS `config`, `data` and `state` collapse to `~/Library/Application Support/<ns>` while `cache` stays under `~/Library/Caches/<ns>`; on Windows they split across `%APPDATA%` and `%LOCALAPPDATA%`. Everywhere else it returns `Option.none()`, because on Linux XDG *is* the native convention and there is nothing to override.
+
+The platform is a `Context.Reference`, never a global read. Pin it in a test with `Layer.succeed(CurrentPlatform, "win32")` and exercise the Windows paths on a Mac.
+
+## Config files
+
+`XdgConfig` is the bridge into `@effected/config-file`. `resolver` searches the app's whole config search path, `nativeResolver` probes the OS-native directory, and `savePath` names the default write target:
+
+```ts
+import { ConfigFile, JsonCodec, MergeStrategy } from "@effected/config-file";
+import { XdgConfig } from "@effected/xdg";
+import { Schema } from "effect";
+
+class AppShape extends Schema.Class<AppShape>("AppShape")({
+  port: Schema.Number,
+  host: Schema.String,
+}) {}
+
+class AppConfig extends ConfigFile.Service<AppConfig, AppShape>()("myapp/Config") {}
+
+export const AppConfigLive = ConfigFile.layer(AppConfig, {
+  schema: AppShape,
+  codec: JsonCodec,
+  resolvers: [
+    XdgConfig.resolver({ filename: "config.json" }),
+    XdgConfig.nativeResolver({ namespace: "myapp", filename: "config.json" }),
+  ],
+  strategy: MergeStrategy.firstMatch<AppShape>(),
+  defaultPath: XdgConfig.savePath("config.json"),
+});
+```
+
+Order matters: put `resolver` before `nativeResolver` so an existing `~/.config/<app>/config.json` still wins over the OS-native directory. `savePath` does not create the directory — `ConfigFile.save` already creates the parent of whatever path it is handed.
+
+## Errors
+
+| Tag | Means | Recovery |
+| --- | --- | --- |
+| `XdgEnvError` | `$HOME` is not set. Carries `variable` and the structural `cause` — the underlying `ConfigError`. | The one environment failure there is. Every other XDG variable is optional by construction, and its absence is a resolved default rather than an error. |
+| `AppDirsError` | A directory could not be created. Carries `directory` (which kind), `path` and the structural `cause`. | The only way `AppDirs` fails, because resolution already happened. Check permissions. |
+
+A namespace that is empty, or contains a path separator, or is exactly `.` or `..`, is a **defect** at layer construction rather than a typed error. It can only come from code, and `namespace: "../.."` would resolve the application's directories outside `$HOME` entirely.
+
+## Features
+
+- `Xdg` / `XdgPaths` — the resolved XDG environment as a value, including the `$XDG_CONFIG_DIRS` and `$XDG_DATA_DIRS` search paths, split and defaulted per the spec. `Xdg.layerFrom` serves fixed paths for tests.
+- `AppDirs` / `ResolvedAppDirs` — the five app-namespaced directories plus the config and data search paths, with `ensureConfig`, `ensureData`, `ensureCache`, `ensureState`, `ensureRuntime` and `ensure` for on-demand creation.
+- `NativeDirs` — the macOS and Windows conventions, resolved purely from a platform, a namespace and an environment.
+- `CurrentPlatform` — the platform as a `Context.Reference`, defaulting to `process.platform` and overridable in a test.
+- `XdgConfig` — `resolver`, `nativeResolver` and `savePath`, dropping straight into `@effected/config-file`'s `ConfigResolver` and `defaultPath` slots.
+- `XdgEnvError` / `AppDirsError` — tagged errors carrying their cause structurally.
+
+## License
+
+[MIT](LICENSE)

package/Xdg.js

@@ -0,0 +1,189 @@
+import { Config, Context, Effect, Layer, Option, Schema } from "effect";
+
+//#region src/Xdg.ts
+/**
+* The operating system the path decisions are taken against.
+*
+* @remarks
+* The members are Node's `process.platform` values, modeled as a schema rather
+* than borrowed from the ambient `NodeJS.Platform` type so the package's public
+* surface names nothing it does not own.
+*
+* @public
+*/
+const XdgPlatform = Schema.Literals([
+	"aix",
+	"android",
+	"darwin",
+	"freebsd",
+	"haiku",
+	"linux",
+	"openbsd",
+	"sunos",
+	"win32",
+	"cygwin",
+	"netbsd"
+]);
+const detectPlatform = () => {
+	const platform = globalThis.process?.platform;
+	return Schema.is(XdgPlatform)(platform) ? platform : "linux";
+};
+/**
+* The platform every native-directory decision is taken against.
+*
+* @remarks
+* A {@link https://effect.website | Context.Reference}, not a global read. It
+* defaults to `process.platform`, so production behaviour is what you expect;
+* a test pins macOS or Windows semantics with
+* `Layer.succeed(CurrentPlatform, "win32")` and exercises the whole native-path
+* matrix without touching a real filesystem or the real platform.
+*
+* @public
+*/
+const CurrentPlatform = Context.Reference("@effected/xdg/CurrentPlatform", { defaultValue: detectPlatform });
+/**
+* Indicates that the environment cannot satisfy XDG directory resolution.
+*
+* @remarks
+* Raised only for `HOME`: every other XDG variable is optional by construction,
+* and its absence is a resolved default rather than a failure. `cause` carries
+* the underlying `ConfigError` structurally — v3 flattened it to a string.
+*
+* @public
+*/
+var XdgEnvError = class extends Schema.TaggedErrorClass()("XdgEnvError", {
+	/** The environment variable that was required and not found. */
+	variable: Schema.String,
+	/** The underlying failure, preserved structurally. */
+	cause: Schema.Defect()
+}) {
+	get message() {
+		return `The ${this.variable} environment variable is not set`;
+	}
+};
+/**
+* The XDG Base Directory environment, resolved.
+*
+* @remarks
+* Every field but `home` is optional because the corresponding variable is:
+* `Schema.optionalKey`, so an unset variable is an **absent key** and the read
+* is `paths.configHome ?? fallback`. v3 modeled these as `Option`, which forced
+* `Option.some(...)` into the construction API of everything downstream.
+*
+* `configDirs` and `dataDirs` are the colon-separated system search paths, split
+* and defaulted per the spec (`/etc/xdg` and `/usr/local/share:/usr/share`).
+* They are what make a config lookup a genuine ordered search rather than a
+* single stat.
+*
+* @public
+*/
+var XdgPaths = class extends Schema.Class("XdgPaths")({
+	/** `$HOME`. The one variable that must be set. */
+	home: Schema.String,
+	/** `$XDG_CONFIG_HOME`. */
+	configHome: Schema.optionalKey(Schema.String),
+	/** `$XDG_DATA_HOME`. */
+	dataHome: Schema.optionalKey(Schema.String),
+	/** `$XDG_CACHE_HOME`. */
+	cacheHome: Schema.optionalKey(Schema.String),
+	/** `$XDG_STATE_HOME`. */
+	stateHome: Schema.optionalKey(Schema.String),
+	/** `$XDG_RUNTIME_DIR`. Absent on most non-Linux systems. */
+	runtimeDir: Schema.optionalKey(Schema.String),
+	/** `%APPDATA%`, on Windows. */
+	appData: Schema.optionalKey(Schema.String),
+	/** `%LOCALAPPDATA%`, on Windows. */
+	localAppData: Schema.optionalKey(Schema.String),
+	/** `$XDG_CONFIG_DIRS`, split on `:`. Defaults to `["/etc/xdg"]`. */
+	configDirs: Schema.Array(Schema.String),
+	/** `$XDG_DATA_DIRS`, split on `:`. Defaults to `["/usr/local/share", "/usr/share"]`. */
+	dataDirs: Schema.Array(Schema.String)
+}) {};
+/**
+* Split a `PATH`-style variable, dropping empty entries.
+*
+* @remarks
+* Per the XDG spec, an unset **or empty** variable takes the default — so
+* `XDG_CONFIG_DIRS=""` is not "no system directories", it is `/etc/xdg`.
+*/
+const splitDirs = (raw, fallback) => {
+	if (raw === void 0) return fallback;
+	const parts = raw.split(":").filter((entry) => entry.length > 0);
+	return parts.length === 0 ? fallback : parts;
+};
+/**
+* XDG Base Directory environment resolution.
+*
+* @remarks
+* The service's shape **is** {@link XdgPaths}: the environment is read once, at
+* layer construction, and the service is the resolved value. v3 exposed nine
+* `Effect`s that each re-read the environment on every access, which is why
+* every path downstream of it was fallible. Here `yield* Xdg` gives you a record
+* of strings, and the only failure — an unset `HOME` — happens once, where the
+* layer is built.
+*
+* @public
+*/
+var Xdg = class Xdg extends Context.Service()("@effected/xdg/Xdg") {
+	/**
+	* Read the XDG environment through Effect's `Config`.
+	*
+	* @remarks
+	* Reads from the ambient `ConfigProvider`, which defaults to `process.env`.
+	* A test drives it with `ConfigProvider.layer(ConfigProvider.fromUnknown({…}))`
+	* and never mutates the real environment.
+	*/
+	static layer = Layer.effect(Xdg, Effect.gen(function* () {
+		/**
+		* `Config<T>` IS an `Effect<T, ConfigError>` in v4, so it pipes directly.
+		* Every `ConfigError` becomes an `XdgEnvError` naming the variable it came from.
+		*/
+		const asEnvError = (name, config) => Effect.catchTag(config, "ConfigError", (cause) => Effect.fail(new XdgEnvError({
+			variable: name,
+			cause
+		})));
+		const home = yield* asEnvError("HOME", Config.string("HOME"));
+		/**
+		* An unset variable is `Option.none()`, not a failure. The residual
+		* `ConfigError` a `Config.option` can still raise is a *provider* failure
+		* (a `ConfigProvider` backed by a directory or a `.env` file that cannot be
+		* read), not a missing key — so it is mapped rather than swallowed.
+		*/
+		const read = (name) => Effect.map(asEnvError(name, Config.option(Config.string(name))), Option.getOrUndefined);
+		const configHome = yield* read("XDG_CONFIG_HOME");
+		const dataHome = yield* read("XDG_DATA_HOME");
+		const cacheHome = yield* read("XDG_CACHE_HOME");
+		const stateHome = yield* read("XDG_STATE_HOME");
+		const runtimeDir = yield* read("XDG_RUNTIME_DIR");
+		const appData = yield* read("APPDATA");
+		const localAppData = yield* read("LOCALAPPDATA");
+		const configDirs = yield* read("XDG_CONFIG_DIRS");
+		const dataDirs = yield* read("XDG_DATA_DIRS");
+		return XdgPaths.make({
+			home,
+			...configHome !== void 0 && { configHome },
+			...dataHome !== void 0 && { dataHome },
+			...cacheHome !== void 0 && { cacheHome },
+			...stateHome !== void 0 && { stateHome },
+			...runtimeDir !== void 0 && { runtimeDir },
+			...appData !== void 0 && { appData },
+			...localAppData !== void 0 && { localAppData },
+			configDirs: splitDirs(configDirs, ["/etc/xdg"]),
+			dataDirs: splitDirs(dataDirs, ["/usr/local/share", "/usr/share"])
+		});
+	}));
+	/**
+	* Serve fixed paths instead of reading the environment.
+	*
+	* @remarks
+	* The test layer, and the escape hatch for an application that resolves its
+	* environment some other way. It needs no filesystem — v3's test layer reached
+	* past the platform abstraction for a `node:fs` temp directory.
+	*/
+	static layerFrom(paths) {
+		return Layer.succeed(Xdg, paths);
+	}
+};
+
+//#endregion
+export { CurrentPlatform, Xdg, XdgEnvError, XdgPaths, XdgPlatform };

package/XdgConfig.js

@@ -0,0 +1,115 @@
+import { NativeDirs } from "./NativeDirs.js";
+import { CurrentPlatform, Xdg } from "./Xdg.js";
+import { AppDirs } from "./AppDirs.js";
+import { Effect, FileSystem, Option, Path } from "effect";
+import { Walker } from "@effected/walker";
+
+//#region src/XdgConfig.ts
+/**
+* Search the app's XDG config search path for `filename`.
+*
+* @remarks
+* Probes the app's own config directory first, then each `$XDG_CONFIG_DIRS`
+* entry namespaced — `~/.config/myapp/rc`, then `/etc/xdg/myapp/rc`. v3 probed
+* only the first of those; the system search path is half the XDG spec and it
+* was missing.
+*
+* The scan runs through `Walker.firstMatch`, so a failure on one candidate means
+* "this candidate did not match" and the search continues to the next. That is a
+* bug fixed, not a refactor: v3 wrapped the whole resolver in a single
+* `catchAll`, so an unreadable `/etc/xdg` aborted the probe and hid a perfectly
+* readable `~/.config`. Not-found and cannot-look stay indistinguishable to the
+* caller, which is the resolver contract — `resolve`'s error channel is `never`.
+*
+* Place it **before** `nativeResolver` in a chain, so an existing
+* `~/.config/<app>` still wins over the OS-native directory.
+*
+* @public
+*/
+const resolver = (options) => ({
+	name: "xdg",
+	resolve: Effect.gen(function* () {
+		const appDirs = yield* AppDirs;
+		const path = yield* Path.Path;
+		const fs = yield* FileSystem.FileSystem;
+		const candidates = appDirs.dirs.configSearchPath.map((dir) => path.join(dir, options.filename));
+		return yield* Walker.firstMatch(candidates, (candidate) => fs.exists(candidate));
+	})
+});
+/**
+* Probe the OS-native config directory for `filename`.
+*
+* @remarks
+* Resolves the native config directory for `namespace`
+* (`~/Library/Application Support/<ns>` on macOS, `%APPDATA%\<ns>` on Windows)
+* and checks whether `filename` is there. On Linux and everywhere else
+* {@link NativeDirs.resolve} yields `Option.none()`, so this resolver returns
+* `Option.none()` without probing at all — the XDG resolver already owns
+* `~/.config` there.
+*
+* Takes `namespace` rather than reading it off {@link AppDirs}: the native
+* directory is a property of the OS convention, not of however the app happened
+* to configure its XDG directories, and a caller may well probe a *different*
+* namespace than the one their `AppDirs` was built for.
+*
+* @public
+*/
+const nativeResolver = (options) => ({
+	name: "native",
+	resolve: Effect.gen(function* () {
+		const paths = yield* Xdg;
+		const platform = yield* CurrentPlatform;
+		const path = yield* Path.Path;
+		const fs = yield* FileSystem.FileSystem;
+		const native = NativeDirs.resolve({
+			platform,
+			namespace: options.namespace,
+			paths,
+			path
+		});
+		if (Option.isNone(native)) return Option.none();
+		return yield* Walker.firstMatch([path.join(native.value.config, options.filename)], (candidate) => fs.exists(candidate));
+	})
+});
+/**
+* The default save target for a config file: `<app config dir>/<filename>`.
+*
+* @remarks
+* Drops straight into `ConfigFileOptions.defaultPath`, whose slot is typed
+* `Effect<string, never, RR>`. That infallible channel is the whole reason
+* {@link AppDirs} resolves at layer-construction time: with v3's per-access
+* resolution this could fail, and a consumer had to `orDie` it into the slot.
+*
+* It does **not** create the directory — `ConfigFile.save` already `mkdir -p`s
+* the parent of whatever path it is given.
+*
+* @example
+* ```ts
+* const layer = ConfigFile.layer(AppConfig, {
+* 	schema: AppShape,
+* 	codec: JsonCodec,
+* 	strategy: MergeStrategy.firstMatch<AppShape>(),
+* 	resolvers: [XdgConfig.resolver({ filename: "config.json" })],
+* 	defaultPath: XdgConfig.savePath("config.json"),
+* });
+* ```
+*
+* @public
+*/
+const savePath = (filename) => Effect.gen(function* () {
+	const appDirs = yield* AppDirs;
+	return (yield* Path.Path).join(appDirs.dirs.config, filename);
+});
+/**
+* The bridge from XDG directories into `@effected/config-file`.
+*
+* @public
+*/
+const XdgConfig = {
+	resolver,
+	nativeResolver,
+	savePath
+};
+
+//#endregion
+export { XdgConfig };

package/index.d.ts

@@ -0,0 +1,392 @@
+import { Context, Effect, FileSystem, Layer, Option, Path, Schema } from "effect";
+import { ConfigResolver } from "@effected/config-file";
+//#region src/Xdg.d.ts
+/**
+ * The operating system the path decisions are taken against.
+ *
+ * @remarks
+ * The members are Node's `process.platform` values, modeled as a schema rather
+ * than borrowed from the ambient `NodeJS.Platform` type so the package's public
+ * surface names nothing it does not own.
+ *
+ * @public
+ */
+declare const XdgPlatform: Schema.Literals<readonly ["aix", "android", "darwin", "freebsd", "haiku", "linux", "openbsd", "sunos", "win32", "cygwin", "netbsd"]>;
+/**
+ * The decoded form of {@link (XdgPlatform:variable)}.
+ *
+ * @public
+ */
+type XdgPlatform = typeof XdgPlatform.Type;
+/**
+ * The platform every native-directory decision is taken against.
+ *
+ * @remarks
+ * A {@link https://effect.website | Context.Reference}, not a global read. It
+ * defaults to `process.platform`, so production behaviour is what you expect;
+ * a test pins macOS or Windows semantics with
+ * `Layer.succeed(CurrentPlatform, "win32")` and exercises the whole native-path
+ * matrix without touching a real filesystem or the real platform.
+ *
+ * @public
+ */
+declare const CurrentPlatform: Context.Reference<XdgPlatform>;
+declare const XdgEnvError_base: Schema.Class<XdgEnvError, Schema.TaggedStruct<"XdgEnvError", {
+  /** The environment variable that was required and not found. */
+  readonly variable: Schema.String;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Indicates that the environment cannot satisfy XDG directory resolution.
+ *
+ * @remarks
+ * Raised only for `HOME`: every other XDG variable is optional by construction,
+ * and its absence is a resolved default rather than a failure. `cause` carries
+ * the underlying `ConfigError` structurally — v3 flattened it to a string.
+ *
+ * @public
+ */
+declare class XdgEnvError extends XdgEnvError_base {
+  get message(): string;
+}
+declare const XdgPaths_base: Schema.Class<XdgPaths, Schema.Struct<{
+  /** `$HOME`. The one variable that must be set. */
+  readonly home: Schema.String;
+  /** `$XDG_CONFIG_HOME`. */
+  readonly configHome: Schema.optionalKey<Schema.String>;
+  /** `$XDG_DATA_HOME`. */
+  readonly dataHome: Schema.optionalKey<Schema.String>;
+  /** `$XDG_CACHE_HOME`. */
+  readonly cacheHome: Schema.optionalKey<Schema.String>;
+  /** `$XDG_STATE_HOME`. */
+  readonly stateHome: Schema.optionalKey<Schema.String>;
+  /** `$XDG_RUNTIME_DIR`. Absent on most non-Linux systems. */
+  readonly runtimeDir: Schema.optionalKey<Schema.String>;
+  /** `%APPDATA%`, on Windows. */
+  readonly appData: Schema.optionalKey<Schema.String>;
+  /** `%LOCALAPPDATA%`, on Windows. */
+  readonly localAppData: Schema.optionalKey<Schema.String>;
+  /** `$XDG_CONFIG_DIRS`, split on `:`. Defaults to `["/etc/xdg"]`. */
+  readonly configDirs: Schema.$Array<Schema.String>;
+  /** `$XDG_DATA_DIRS`, split on `:`. Defaults to `["/usr/local/share", "/usr/share"]`. */
+  readonly dataDirs: Schema.$Array<Schema.String>;
+}>, {}>;
+/**
+ * The XDG Base Directory environment, resolved.
+ *
+ * @remarks
+ * Every field but `home` is optional because the corresponding variable is:
+ * `Schema.optionalKey`, so an unset variable is an **absent key** and the read
+ * is `paths.configHome ?? fallback`. v3 modeled these as `Option`, which forced
+ * `Option.some(...)` into the construction API of everything downstream.
+ *
+ * `configDirs` and `dataDirs` are the colon-separated system search paths, split
+ * and defaulted per the spec (`/etc/xdg` and `/usr/local/share:/usr/share`).
+ * They are what make a config lookup a genuine ordered search rather than a
+ * single stat.
+ *
+ * @public
+ */
+declare class XdgPaths extends XdgPaths_base {}
+declare const Xdg_base: Context.ServiceClass<Xdg, "@effected/xdg/Xdg", XdgPaths>;
+/**
+ * XDG Base Directory environment resolution.
+ *
+ * @remarks
+ * The service's shape **is** {@link XdgPaths}: the environment is read once, at
+ * layer construction, and the service is the resolved value. v3 exposed nine
+ * `Effect`s that each re-read the environment on every access, which is why
+ * every path downstream of it was fallible. Here `yield* Xdg` gives you a record
+ * of strings, and the only failure — an unset `HOME` — happens once, where the
+ * layer is built.
+ *
+ * @public
+ */
+declare class Xdg extends Xdg_base {
+  /**
+   * Read the XDG environment through Effect's `Config`.
+   *
+   * @remarks
+   * Reads from the ambient `ConfigProvider`, which defaults to `process.env`.
+   * A test drives it with `ConfigProvider.layer(ConfigProvider.fromUnknown({…}))`
+   * and never mutates the real environment.
+   */
+  static readonly layer: Layer.Layer<Xdg, XdgEnvError>;
+  /**
+   * Serve fixed paths instead of reading the environment.
+   *
+   * @remarks
+   * The test layer, and the escape hatch for an application that resolves its
+   * environment some other way. It needs no filesystem — v3's test layer reached
+   * past the platform abstraction for a `node:fs` temp directory.
+   */
+  static layerFrom(paths: XdgPaths): Layer.Layer<Xdg>;
+}
+//#endregion
+//#region src/AppDirs.d.ts
+/**
+ * The four directory kinds XDG separates, plus the runtime directory.
+ *
+ * @public
+ */
+declare const AppDirKind: Schema.Literals<readonly ["config", "data", "cache", "state", "runtime"]>;
+/**
+ * The decoded form of {@link (AppDirKind:variable)}.
+ *
+ * @public
+ */
+type AppDirKind = typeof AppDirKind.Type;
+declare const AppDirsError_base: Schema.Class<AppDirsError, Schema.TaggedStruct<"AppDirsError", {
+  /** Which directory kind failed. */
+  readonly directory: Schema.Literals<readonly ["config", "data", "cache", "state", "runtime"]>;
+  /** The path that could not be created. */
+  readonly path: Schema.String;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Indicates that an application directory could not be created.
+ *
+ * @remarks
+ * The only way `AppDirs` fails. Resolution cannot fail — it happens once, at
+ * layer construction, from an environment that is already resolved — so this
+ * error means exactly one thing: the `mkdir -p` did not work. `directory` says
+ * which kind, `path` says where, and `cause` carries the underlying
+ * `PlatformError` structurally. v3 carried `reason: String(e)` and a `directory`
+ * that could also be the string `"all"`.
+ *
+ * @public
+ */
+declare class AppDirsError extends AppDirsError_base {
+  get message(): string;
+}
+declare const ResolvedAppDirs_base: Schema.Class<ResolvedAppDirs, Schema.Struct<{
+  /** The app's configuration directory. */
+  readonly config: Schema.String;
+  /** The app's data directory. */
+  readonly data: Schema.String;
+  /** The app's cache directory. */
+  readonly cache: Schema.String;
+  /** The app's state directory. */
+  readonly state: Schema.String;
+  /**
+   * The app's runtime directory.
+   *
+   * @remarks
+   * Absent unless `$XDG_RUNTIME_DIR` is set or `dirs.runtime` overrides it.
+   * There is no defensible fallback for a runtime directory — it must be
+   * user-owned, mode 0700 and cleaned on logout — so inventing one would be a
+   * lie, and the key is simply absent.
+   */
+  readonly runtime: Schema.optionalKey<Schema.String>;
+  /**
+   * Where to **look** for configuration, in priority order.
+   *
+   * @remarks
+   * The app's own config directory, then each `$XDG_CONFIG_DIRS` entry
+   * namespaced. This is the half of the XDG spec v3 ignored entirely, and it is
+   * what makes {@link XdgConfig.resolver} a real search rather than a single stat.
+   */
+  readonly configSearchPath: Schema.$Array<Schema.String>;
+  /** Where to look for data files, in priority order. */
+  readonly dataSearchPath: Schema.$Array<Schema.String>;
+}>, {}>;
+/**
+ * The fully resolved, app-namespaced directories.
+ *
+ * @public
+ */
+declare class ResolvedAppDirs extends ResolvedAppDirs_base {}
+/**
+ * Per-kind absolute directory overrides. Each wins outright over every other rung.
+ *
+ * @public
+ */
+interface AppDirOverrides {
+  /** An absolute path for the config directory. */
+  readonly config?: string;
+  /** An absolute path for the data directory. */
+  readonly data?: string;
+  /** An absolute path for the cache directory. */
+  readonly cache?: string;
+  /** An absolute path for the state directory. */
+  readonly state?: string;
+  /** An absolute path for the runtime directory. */
+  readonly runtime?: string;
+}
+/**
+ * Options for {@link AppDirs.layer}.
+ *
+ * @remarks
+ * Plain optional fields, not `Option`s: v3 made callers write
+ * `fallbackDir: Option.some(".myapp"), dirs: Option.none()`. `Option` is an
+ * internal representation, not an input format.
+ *
+ * @public
+ */
+interface AppDirsOptions {
+  /**
+   * The application namespace — one path component.
+   *
+   * @remarks
+   * Must be non-empty and free of path separators. A namespace containing `..`
+   * or `/` would resolve the app's directories outside `$HOME` entirely, so it
+   * is rejected as a **defect** at layer construction: it can only come from
+   * code, never from user input.
+   */
+  readonly namespace: string;
+  /**
+   * Use the OS-native directories where the platform has them. Defaults to `false`.
+   *
+   * @remarks
+   * Only consulted when no XDG variable and no explicit override applies, and
+   * only on darwin and win32 — on Linux there is nothing to override.
+   */
+  readonly native?: boolean;
+  /**
+   * A single dot-directory under `$HOME` that all four kinds collapse to.
+   *
+   * @remarks
+   * Relative to `$HOME`: `fallbackDir: ".myapp"` gives `$HOME/.myapp`.
+   */
+  readonly fallbackDir?: string;
+  /** Absolute per-kind overrides. */
+  readonly dirs?: AppDirOverrides;
+}
+/**
+ * App-namespaced directory resolution and on-demand creation.
+ *
+ * @remarks
+ * `dirs` is a **value**, not an `Effect`: the environment is fixed when the
+ * layer is built, so resolution happens there, exactly once. Reading a path
+ * cannot fail and cannot be observed to do IO. Only the `ensure*` operations
+ * touch the filesystem, and they are the only fallible members.
+ *
+ * @public
+ */
+interface AppDirsShape {
+  /** The namespace these directories were resolved for. */
+  readonly namespace: string;
+  /** The resolved directories. Reading them cannot fail. */
+  readonly dirs: ResolvedAppDirs;
+  /** Create the config directory if it does not exist, and return it. */
+  readonly ensureConfig: Effect.Effect<string, AppDirsError>;
+  /** Create the data directory if it does not exist, and return it. */
+  readonly ensureData: Effect.Effect<string, AppDirsError>;
+  /** Create the cache directory if it does not exist, and return it. */
+  readonly ensureCache: Effect.Effect<string, AppDirsError>;
+  /** Create the state directory if it does not exist, and return it. */
+  readonly ensureState: Effect.Effect<string, AppDirsError>;
+  /**
+   * Create the runtime directory if there is one, and return it.
+   *
+   * @remarks
+   * `Option.none()` when no runtime directory is configured — nothing is created
+   * and nothing fails.
+   */
+  readonly ensureRuntime: Effect.Effect<Option.Option<string>, AppDirsError>;
+  /** Create every directory that exists in the resolution, and return them all. */
+  readonly ensure: Effect.Effect<ResolvedAppDirs, AppDirsError>;
+}
+declare const AppDirs_base: Context.ServiceClass<AppDirs, "@effected/xdg/AppDirs", AppDirsShape>;
+/**
+ * App-namespaced XDG directories, with on-demand creation.
+ *
+ * @remarks
+ * `AppDirs.layer` is a layer-**returning function**: calling it twice builds two
+ * independent services. Bind its result to a const and provide that const, per
+ * the layer memoization discipline.
+ *
+ * @example
+ * ```ts
+ * const AppDirsLayer = AppDirs.layer({ namespace: "myapp", native: true });
+ * const XdgLayer = Layer.mergeAll(Xdg.layer, AppDirsLayer.pipe(Layer.provide(Xdg.layer)));
+ * ```
+ *
+ * @public
+ */
+declare class AppDirs extends AppDirs_base {
+  /**
+   * Resolve the namespace's directories against the ambient {@link Xdg}
+   * environment and platform.
+   *
+   * @remarks
+   * The error channel is `never`. The one failure that could happen during
+   * resolution — an unset `HOME` — surfaces on {@link Xdg.layer} as an
+   * `XdgEnvError`, before an `AppDirs` exists at all. v3 laundered it into an
+   * `AppDirsError({ directory: "all" })`.
+   */
+  static layer(options: AppDirsOptions): Layer.Layer<AppDirs, never, Xdg | FileSystem.FileSystem | Path.Path>;
+}
+//#endregion
+//#region src/NativeDirs.d.ts
+declare const NativeDirs_base: Schema.Class<NativeDirs, Schema.Struct<{
+  /** Where configuration lives. */
+  readonly config: Schema.String;
+  /** Where application data lives. */
+  readonly data: Schema.String;
+  /** Where discardable cached data lives. */
+  readonly cache: Schema.String;
+  /** Where persistent-but-regenerable state lives. */
+  readonly state: Schema.String;
+}>, {}>;
+/**
+ * The OS-native application directories for one namespace.
+ *
+ * @remarks
+ * On platforms without OS-level separation of these concerns, `config`, `data`
+ * and `state` collapse to the same directory — `~/Library/Application Support/<ns>`
+ * on macOS — while `cache` stays distinct.
+ *
+ * @public
+ */
+declare class NativeDirs extends NativeDirs_base {
+  /**
+   * Map a platform and an environment onto the native directories for a namespace.
+   *
+   * @remarks
+   * **Pure**: no filesystem, no environment, no `process.platform`. Every input
+   * is a parameter, which is what makes the whole platform matrix testable
+   * without any platform IO. Paths are joined through the supplied `Path`, so a
+   * win32 `Path` layer yields win32 separators — v3 interpolated `/` on every
+   * platform.
+   *
+   * - **darwin** — `config`/`data`/`state` under `~/Library/Application Support/<ns>`;
+   *   `cache` under `~/Library/Caches/<ns>`.
+   * - **win32** — `config`/`data` under `%APPDATA%/<ns>`; `cache` under
+   *   `%LOCALAPPDATA%/<ns>/Cache`; `state` under `%LOCALAPPDATA%/<ns>`. When the
+   *   variables are unset, `%APPDATA%` falls back to `<home>/AppData/Roaming` and
+   *   `%LOCALAPPDATA%` to `<home>/AppData/Local`.
+   * - **everything else** — `Option.none()`. On Linux, XDG *is* the native
+   *   convention, so there is no override to apply; returning `none` rather than
+   *   a duplicate of the XDG answer is what lets a precedence ladder skip the
+   *   rung cleanly instead of shadowing the rung below it.
+   */
+  static resolve(input: {
+    readonly platform: XdgPlatform;
+    readonly namespace: string;
+    readonly paths: XdgPaths;
+    readonly path: Path.Path;
+  }): Option.Option<NativeDirs>;
+}
+//#endregion
+//#region src/XdgConfig.d.ts
+/**
+ * The bridge from XDG directories into `@effected/config-file`.
+ *
+ * @public
+ */
+declare const XdgConfig: {
+  readonly resolver: (options: {
+    readonly filename: string;
+  }) => ConfigResolver<AppDirs | FileSystem.FileSystem | Path.Path>;
+  readonly nativeResolver: (options: {
+    readonly namespace: string;
+    readonly filename: string;
+  }) => ConfigResolver<Xdg | FileSystem.FileSystem | Path.Path>;
+  readonly savePath: (filename: string) => Effect.Effect<string, never, AppDirs | Path.Path>;
+};
+//#endregion
+export { AppDirKind, type AppDirOverrides, AppDirs, AppDirsError, type AppDirsOptions, type AppDirsShape, CurrentPlatform, NativeDirs, ResolvedAppDirs, Xdg, XdgConfig, XdgEnvError, XdgPaths, XdgPlatform };
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,6 @@
+import { NativeDirs } from "./NativeDirs.js";
+import { CurrentPlatform, Xdg, XdgEnvError, XdgPaths, XdgPlatform } from "./Xdg.js";
+import { AppDirKind, AppDirs, AppDirsError, ResolvedAppDirs } from "./AppDirs.js";
+import { XdgConfig } from "./XdgConfig.js";
+
+export { AppDirKind, AppDirs, AppDirsError, CurrentPlatform, NativeDirs, ResolvedAppDirs, Xdg, XdgConfig, XdgEnvError, XdgPaths, XdgPlatform };

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "@effected/xdg",
+	"version": "0.1.0",
+	"private": false,
+	"description": "XDG Base Directory resolution for Effect: environment paths, app-namespaced directories, native OS conventions and config-file resolvers.",
+	"keywords": [
+		"xdg",
+		"basedir",
+		"appdirs",
+		"config",
+		"paths",
+		"effect",
+		"effected"
+	],
+	"homepage": "https://github.com/spencerbeggs/effected/tree/main/packages/xdg#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/effected/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/effected.git",
+		"directory": "packages/xdg"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"peerDependencies": {
+		"@effected/config-file": "0.1.0",
+		"@effected/walker": "0.1.0",
+		"effect": "4.0.0-beta.98"
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.58.9"
+    }
+  ]
+}