@outfitter/config 0.3.4 → 0.4.0

package/dist/index.d.ts

@@ -1,214 +1,10 @@
 import { Env, booleanSchema, env, getEnvBoolean, optionalBooleanSchema, parseEnv, portSchema } from "./shared/@outfitter/config-veqxf02x.js";
 import { EnvironmentDefaults, OutfitterEnv, getEnvironment, getEnvironmentDefaults } from "./shared/@outfitter/config-wawavx3r.js";
-import { TaggedErrorClass } from "@outfitter/contracts";
-import { NotFoundError, Result, ValidationError } from "@outfitter/contracts";
+import { getCacheDir, getConfigDir, getDataDir, getStateDir } from "./shared/@outfitter/config-6449x3br.js";
+import { LoadConfigOptions, loadConfig } from "./shared/@outfitter/config-7dyshh4r.js";
+import { CircularExtendsError, ParseError, deepMerge, parseConfigFile } from "./shared/@outfitter/config-sp6gradd.js";
+import { Result, ValidationError } from "@outfitter/contracts";
 import { ZodSchema } from "zod";
-type ParseErrorFields = {
-	/** Human-readable error message describing the parse failure */
-	message: string;
-	/** Name of the file that failed to parse */
-	filename: string;
-	/** Line number where the error occurred (if available) */
-	line?: number;
-	/** Column number where the error occurred (if available) */
-	column?: number;
-};
-declare const ParseErrorBase: TaggedErrorClass<"ParseError", ParseErrorFields>;
-/**
-* Error thrown when a configuration file cannot be parsed.
-*
-* Contains details about the parse failure including the filename
-* and optionally the line/column where the error occurred.
-*
-* @example
-* ```typescript
-* const result = parseConfigFile("invalid toml [", "config.toml");
-* if (result.isErr() && result.error._tag === "ParseError") {
-*   console.error(`Parse error in ${result.error.filename}: ${result.error.message}`);
-* }
-* ```
-*/
-declare class ParseError extends ParseErrorBase {
-	readonly category: "validation";
-}
-type CircularExtendsErrorFields = {
-	/** Human-readable error message */
-	message: string;
-	/** The config file paths that form the circular reference */
-	chain: string[];
-};
-declare const CircularExtendsErrorBase: TaggedErrorClass<"CircularExtendsError", CircularExtendsErrorFields>;
-/**
-* Error thrown when a circular extends reference is detected.
-*/
-declare class CircularExtendsError extends CircularExtendsErrorBase {
-	readonly category: "validation";
-}
-/**
-* Get the XDG config directory for an application.
-*
-* Uses `XDG_CONFIG_HOME` if set, otherwise defaults to `~/.config`.
-* This follows the XDG Base Directory Specification for storing
-* user-specific configuration files.
-*
-* @param appName - Application name used as subdirectory
-* @returns Absolute path to the application's config directory
-*
-* @example
-* ```typescript
-* // With XDG_CONFIG_HOME="/custom/config"
-* getConfigDir("myapp"); // "/custom/config/myapp"
-*
-* // Without XDG_CONFIG_HOME (uses default)
-* getConfigDir("myapp"); // "/home/user/.config/myapp"
-* ```
-*/
-declare function getConfigDir(appName: string): string;
-/**
-* Get the XDG data directory for an application.
-*
-* Uses `XDG_DATA_HOME` if set, otherwise defaults to `~/.local/share`.
-* This follows the XDG Base Directory Specification for storing
-* user-specific data files (databases, generated content, etc.).
-*
-* @param appName - Application name used as subdirectory
-* @returns Absolute path to the application's data directory
-*
-* @example
-* ```typescript
-* // With XDG_DATA_HOME="/custom/data"
-* getDataDir("myapp"); // "/custom/data/myapp"
-*
-* // Without XDG_DATA_HOME (uses default)
-* getDataDir("myapp"); // "/home/user/.local/share/myapp"
-* ```
-*/
-declare function getDataDir(appName: string): string;
-/**
-* Get the XDG cache directory for an application.
-*
-* Uses `XDG_CACHE_HOME` if set, otherwise defaults to `~/.cache`.
-* This follows the XDG Base Directory Specification for storing
-* non-essential cached data that can be regenerated.
-*
-* @param appName - Application name used as subdirectory
-* @returns Absolute path to the application's cache directory
-*
-* @example
-* ```typescript
-* // With XDG_CACHE_HOME="/custom/cache"
-* getCacheDir("myapp"); // "/custom/cache/myapp"
-*
-* // Without XDG_CACHE_HOME (uses default)
-* getCacheDir("myapp"); // "/home/user/.cache/myapp"
-* ```
-*/
-declare function getCacheDir(appName: string): string;
-/**
-* Get the XDG state directory for an application.
-*
-* Uses `XDG_STATE_HOME` if set, otherwise defaults to `~/.local/state`.
-* This follows the XDG Base Directory Specification for storing
-* state data that should persist between restarts (logs, history, etc.).
-*
-* @param appName - Application name used as subdirectory
-* @returns Absolute path to the application's state directory
-*
-* @example
-* ```typescript
-* // With XDG_STATE_HOME="/custom/state"
-* getStateDir("myapp"); // "/custom/state/myapp"
-*
-* // Without XDG_STATE_HOME (uses default)
-* getStateDir("myapp"); // "/home/user/.local/state/myapp"
-* ```
-*/
-declare function getStateDir(appName: string): string;
-/**
-* Deep merge two objects with configurable merge semantics.
-*
-* Merge behavior:
-* - Recursively merges nested plain objects
-* - Arrays are replaced (not concatenated)
-* - `null` explicitly replaces the target value
-* - `undefined` is skipped (does not override)
-*
-* @typeParam T - The type of the target object
-* @param target - Base object to merge into (not mutated)
-* @param source - Object with values to merge
-* @returns New object with merged values
-*
-* @example
-* ```typescript
-* const defaults = { server: { port: 3000, host: "localhost" } };
-* const overrides = { server: { port: 8080 } };
-*
-* const merged = deepMerge(defaults, overrides);
-* // { server: { port: 8080, host: "localhost" } }
-* ```
-*
-* @example
-* ```typescript
-* // Arrays replace, not merge
-* const target = { tags: ["a", "b"] };
-* const source = { tags: ["c"] };
-* deepMerge(target, source); // { tags: ["c"] }
-*
-* // undefined is skipped
-* const base = { a: 1, b: 2 };
-* deepMerge(base, { a: undefined, b: 3 }); // { a: 1, b: 3 }
-*
-* // null explicitly replaces
-* deepMerge(base, { a: null }); // { a: null, b: 2 }
-* ```
-*/
-declare function deepMerge<T extends object>(target: T, source: Partial<T>): T;
-/**
-* Parse configuration file content based on filename extension.
-*
-* Supports multiple formats:
-* - `.toml` - Parsed with smol-toml (preferred for config)
-* - `.yaml`, `.yml` - Parsed with yaml (merge key support enabled)
-* - `.json` - Parsed with strict JSON.parse
-* - `.jsonc` - Parsed with json5 compatibility (comments/trailing commas)
-* - `.json5` - Parsed with json5 (comments and trailing commas allowed)
-*
-* @param content - Raw file content to parse
-* @param filename - Filename used to determine format (by extension)
-* @returns Result containing parsed object or ParseError
-*
-* @example
-* ```typescript
-* const toml = `
-* [server]
-* port = 3000
-* host = "localhost"
-* `;
-*
-* const result = parseConfigFile(toml, "config.toml");
-* if (result.isOk()) {
-*   console.log(result.value.server.port); // 3000
-* }
-* ```
-*
-* @example
-* ```typescript
-* // YAML with anchors/aliases
-* const yaml = `
-* defaults: &defaults
-*   timeout: 5000
-* server:
-*   <<: *defaults
-*   port: 3000
-* `;
-*
-* const result = parseConfigFile(yaml, "config.yaml");
-* if (result.isOk()) {
-*   console.log(result.value.server.timeout); // 5000
-* }
-* ```
-*/
-declare function parseConfigFile(content: string, filename: string): Result<Record<string, unknown>, InstanceType<typeof ParseError>>;
 /**
 * Configuration sources for multi-layer resolution.
 *
@@ -274,73 +70,6 @@ interface ConfigSources<T> {
 */
 declare function resolveConfig<T>(schema: ZodSchema<T>, sources: ConfigSources<T>): Result<T, InstanceType<typeof ValidationError> | InstanceType<typeof ParseError>>;
 /**
-* Options for the {@link loadConfig} function.
-*
-* @example
-* ```typescript
-* const options: LoadConfigOptions = {
-*   searchPaths: ["/etc/myapp", "/opt/myapp/config"],
-* };
-* ```
-*/
-interface LoadConfigOptions {
-	/**
-	* Custom search paths to check for config files.
-	* When provided, overrides the default XDG-based search paths.
-	* Paths are searched in order; first match wins.
-	*/
-	searchPaths?: string[];
-}
-/**
-* Load configuration for an application from XDG-compliant paths.
-*
-* Search order (first found wins):
-* 1. Custom `searchPaths` if provided in options
-* 2. `$XDG_CONFIG_HOME/{appName}/config.{ext}`
-* 3. `~/.config/{appName}/config.{ext}`
-*
-* File format preference: `.toml` > `.yaml` > `.yml` > `.json` > `.jsonc` > `.json5`
-*
-* @typeParam T - The configuration type (inferred from schema)
-* @param appName - Application name for XDG directory lookup
-* @param schema - Zod schema for validation
-* @param options - Optional configuration (custom search paths)
-* @returns Result containing validated config or NotFoundError/ValidationError/ParseError
-*
-* @example
-* ```typescript
-* import { loadConfig } from "@outfitter/config";
-* import { z } from "zod";
-*
-* const AppConfigSchema = z.object({
-*   apiKey: z.string(),
-*   timeout: z.number().default(5000),
-*   features: z.object({
-*     darkMode: z.boolean().default(false),
-*   }),
-* });
-*
-* // Searches ~/.config/myapp/config.{toml,yaml,json,...}
-* const result = await loadConfig("myapp", AppConfigSchema);
-*
-* if (result.isOk()) {
-*   console.log("API Key:", result.value.apiKey);
-*   console.log("Timeout:", result.value.timeout);
-* } else {
-*   console.error("Failed to load config:", result.error.message);
-* }
-* ```
-*
-* @example
-* ```typescript
-* // With custom search paths
-* const result = await loadConfig("myapp", AppConfigSchema, {
-*   searchPaths: ["/etc/myapp", "/opt/myapp/config"],
-* });
-* ```
-*/
-declare function loadConfig<T>(appName: string, schema: ZodSchema<T>, options?: LoadConfigOptions): Result<T, InstanceType<typeof NotFoundError> | InstanceType<typeof ValidationError> | InstanceType<typeof ParseError> | InstanceType<typeof CircularExtendsError>>;
-/**
 * Map environment variables to config object based on prefix.
 *
 * Environment variables are mapped as follows:

package/dist/index.js

@@ -11,132 +11,25 @@ import {
   getEnvironment,
   getEnvironmentDefaults
 } from "./shared/@outfitter/config-w3pwcpr2.js";
-
-// packages/config/src/index.ts
-import { existsSync, readFileSync } from "fs";
-import { dirname, isAbsolute, join, resolve } from "path";
 import {
-  NotFoundError,
-  Result,
-  TaggedError,
-  ValidationError
-} from "@outfitter/contracts";
-import { parse as parseToml } from "smol-toml";
-import { parse as parseYaml } from "yaml";
-var ParseErrorBase = TaggedError("ParseError")();
-
-class ParseError extends ParseErrorBase {
-  category = "validation";
-}
-var CircularExtendsErrorBase = TaggedError("CircularExtendsError")();
+  getCacheDir,
+  getConfigDir,
+  getDataDir,
+  getStateDir
+} from "./shared/@outfitter/config-pf9xp78h.js";
+import {
+  loadConfig
+} from "./shared/@outfitter/config-br341dr7.js";
+import"./shared/@outfitter/config-aje2en96.js";
+import {
+  CircularExtendsError,
+  ParseError,
+  deepMerge,
+  parseConfigFile
+} from "./shared/@outfitter/config-s4swz8m3.js";
 
-class CircularExtendsError extends CircularExtendsErrorBase {
-  category = "validation";
-}
-function getConfigDir(appName) {
-  const xdgConfigHome = process.env["XDG_CONFIG_HOME"];
-  const home = process.env["HOME"] ?? "";
-  const baseDir = xdgConfigHome ?? join(home, ".config");
-  return join(baseDir, appName);
-}
-function getDataDir(appName) {
-  const xdgDataHome = process.env["XDG_DATA_HOME"];
-  const home = process.env["HOME"] ?? "";
-  const baseDir = xdgDataHome ?? join(home, ".local", "share");
-  return join(baseDir, appName);
-}
-function getCacheDir(appName) {
-  const xdgCacheHome = process.env["XDG_CACHE_HOME"];
-  const home = process.env["HOME"] ?? "";
-  const baseDir = xdgCacheHome ?? join(home, ".cache");
-  return join(baseDir, appName);
-}
-function getStateDir(appName) {
-  const xdgStateHome = process.env["XDG_STATE_HOME"];
-  const home = process.env["HOME"] ?? "";
-  const baseDir = xdgStateHome ?? join(home, ".local", "state");
-  return join(baseDir, appName);
-}
-function isPlainObject(value) {
-  if (value === null || typeof value !== "object") {
-    return false;
-  }
-  if (Array.isArray(value)) {
-    return false;
-  }
-  return true;
-}
-function deepMerge(target, source) {
-  const result = { ...target };
-  for (const key of Object.keys(source)) {
-    const sourceValue = source[key];
-    const targetValue = result[key];
-    if (sourceValue === undefined) {
-      continue;
-    }
-    if (sourceValue === null) {
-      result[key] = null;
-      continue;
-    }
-    if (Array.isArray(sourceValue)) {
-      result[key] = sourceValue;
-      continue;
-    }
-    if (isPlainObject(sourceValue) && isPlainObject(targetValue)) {
-      result[key] = deepMerge(targetValue, sourceValue);
-      continue;
-    }
-    result[key] = sourceValue;
-  }
-  return result;
-}
-function getExtension(filename) {
-  const lastDot = filename.lastIndexOf(".");
-  if (lastDot === -1) {
-    return "";
-  }
-  return filename.slice(lastDot + 1).toLowerCase();
-}
-function parseConfigFile(content, filename) {
-  const ext = getExtension(filename);
-  try {
-    switch (ext) {
-      case "toml": {
-        const parsed = parseToml(content);
-        return Result.ok(parsed);
-      }
-      case "yaml":
-      case "yml": {
-        const parsed = parseYaml(content, { merge: true });
-        if (parsed === null || typeof parsed !== "object") {
-          return Result.ok({});
-        }
-        return Result.ok(parsed);
-      }
-      case "json": {
-        const parsed = JSON.parse(content);
-        return Result.ok(parsed);
-      }
-      case "jsonc":
-      case "json5": {
-        const parsed = Bun.JSON5.parse(content);
-        return Result.ok(parsed);
-      }
-      default: {
-        return Result.err(new ParseError({
-          message: `Unsupported config file extension: .${ext}`,
-          filename
-        }));
-      }
-    }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : "Unknown parse error";
-    return Result.err(new ParseError({
-      message: `Failed to parse ${filename}: ${message}`,
-      filename
-    }));
-  }
-}
+// packages/config/src/index.ts
+import { formatZodIssues, Result, ValidationError } from "@outfitter/contracts";
 function resolveConfig(schema, sources) {
   let merged = {};
   if (sources.defaults) {
@@ -153,133 +46,15 @@ function resolveConfig(schema, sources) {
   }
   const parseResult = schema.safeParse(merged);
   if (!parseResult.success) {
-    const issues = parseResult.error.issues;
-    const firstIssue = issues[0];
-    const path = firstIssue?.path?.join(".") ?? "";
-    const message = firstIssue?.message ?? "Validation failed";
-    const fullMessage = path ? `${path}: ${message}` : message;
+    const fullMessage = formatZodIssues(parseResult.error.issues);
+    const firstPath = parseResult.error.issues[0]?.path?.join(".");
     return Result.err(new ValidationError({
       message: fullMessage,
-      ...path ? { field: path } : {}
+      ...firstPath ? { field: firstPath } : {}
     }));
   }
   return Result.ok(parseResult.data);
 }
-var CONFIG_EXTENSIONS = ["toml", "yaml", "yml", "json", "jsonc", "json5"];
-function findConfigFile(dir) {
-  for (const ext of CONFIG_EXTENSIONS) {
-    const filePath = join(dir, `config.${ext}`);
-    if (existsSync(filePath)) {
-      return filePath;
-    }
-  }
-  return;
-}
-function getDefaultSearchPaths(appName) {
-  const xdgConfigHome = process.env["XDG_CONFIG_HOME"];
-  const home = process.env["HOME"] ?? "";
-  const defaultConfigPath = join(home, ".config", appName);
-  if (xdgConfigHome) {
-    const xdgPath = join(xdgConfigHome, appName);
-    if (xdgPath !== defaultConfigPath) {
-      return [xdgPath, defaultConfigPath];
-    }
-  }
-  return [defaultConfigPath];
-}
-function loadConfig(appName, schema, options) {
-  const searchPaths = options?.searchPaths ? options.searchPaths.map((p) => join(p, appName)) : getDefaultSearchPaths(appName);
-  let configFilePath;
-  for (const searchPath of searchPaths) {
-    const found = findConfigFile(searchPath);
-    if (found) {
-      configFilePath = found;
-      break;
-    }
-  }
-  if (!configFilePath) {
-    return Result.err(new NotFoundError({
-      message: `Configuration file not found for ${appName}`,
-      resourceType: "config",
-      resourceId: appName
-    }));
-  }
-  const loadResult = loadConfigFileWithExtends(configFilePath);
-  if (loadResult.isErr()) {
-    return Result.err(loadResult.error);
-  }
-  const parsed = loadResult.unwrap();
-  const validateResult = schema.safeParse(parsed);
-  if (!validateResult.success) {
-    const issues = validateResult.error.issues;
-    const firstIssue = issues[0];
-    const path = firstIssue?.path?.join(".") ?? "";
-    const message = firstIssue?.message ?? "Validation failed";
-    const fullMessage = path ? `${path}: ${message}` : message;
-    return Result.err(new ValidationError({
-      message: fullMessage,
-      ...path ? { field: path } : {}
-    }));
-  }
-  return Result.ok(validateResult.data);
-}
-function resolveExtendsPath(extendsValue, fromFile) {
-  if (isAbsolute(extendsValue)) {
-    return extendsValue;
-  }
-  return resolve(dirname(fromFile), extendsValue);
-}
-function loadConfigFileWithExtends(filePath, visited = new Set) {
-  const normalizedPath = resolve(filePath);
-  if (visited.has(normalizedPath)) {
-    return Result.err(new CircularExtendsError({
-      message: `Circular extends detected: ${[...visited, normalizedPath].join(" -> ")}`,
-      chain: [...visited, normalizedPath]
-    }));
-  }
-  if (!existsSync(filePath)) {
-    return Result.err(new NotFoundError({
-      message: `Config file not found: ${filePath}`,
-      resourceType: "config",
-      resourceId: filePath
-    }));
-  }
-  let content;
-  try {
-    content = readFileSync(filePath, "utf-8");
-  } catch {
-    return Result.err(new NotFoundError({
-      message: `Failed to read config file: ${filePath}`,
-      resourceType: "config",
-      resourceId: filePath
-    }));
-  }
-  const filename = filePath.split("/").pop() ?? "config";
-  const parseResult = parseConfigFile(content, filename);
-  if (parseResult.isErr()) {
-    return Result.err(parseResult.error);
-  }
-  const parsed = parseResult.unwrap();
-  const extendsValue = parsed["extends"];
-  if (extendsValue === undefined) {
-    return Result.ok(parsed);
-  }
-  if (typeof extendsValue !== "string") {
-    return Result.err(new ParseError({
-      message: `Invalid "extends" value in ${filePath}: expected string, got ${typeof extendsValue}`,
-      filename: filePath
-    }));
-  }
-  visited.add(normalizedPath);
-  const extendsPath = resolveExtendsPath(extendsValue, filePath);
-  const baseResult = loadConfigFileWithExtends(extendsPath, visited);
-  if (baseResult.isErr()) {
-    return Result.err(baseResult.error);
-  }
-  const baseConfig = baseResult.unwrap();
-  const { extends: __, ...currentConfig } = parsed;
-  return Result.ok(deepMerge(baseConfig, currentConfig));
-}
 function mapEnvToConfig(prefix, _schema) {
   const result = {};
   const prefixWithUnderscore = `${prefix}_`;

package/dist/internal/extends.d.ts

@@ -0,0 +1,13 @@
+import { CircularExtendsError, ParseError } from "../shared/@outfitter/config-sp6gradd.js";
+import { NotFoundError, Result } from "@outfitter/contracts";
+/**
+* Resolve an extends path relative to the config file that contains it.
+* @internal
+*/
+declare function resolveExtendsPath(extendsValue: string, fromFile: string): string;
+/**
+* Load a config file and recursively resolve any extends references.
+* @internal
+*/
+declare function loadConfigFileWithExtends(filePath: string, visited?: Set<string>): Result<Record<string, unknown>, InstanceType<typeof NotFoundError> | InstanceType<typeof ParseError> | InstanceType<typeof CircularExtendsError>>;
+export { resolveExtendsPath, loadConfigFileWithExtends };

package/dist/internal/extends.js

@@ -0,0 +1,10 @@
+// @bun
+import {
+  loadConfigFileWithExtends,
+  resolveExtendsPath
+} from "../shared/@outfitter/config-aje2en96.js";
+import"../shared/@outfitter/config-s4swz8m3.js";
+export {
+  resolveExtendsPath,
+  loadConfigFileWithExtends
+};

package/dist/internal/loading.d.ts

@@ -0,0 +1,3 @@
+import { LoadConfigOptions, loadConfig } from "../shared/@outfitter/config-7dyshh4r.js";
+import "../shared/@outfitter/config-sp6gradd.js";
+export { loadConfig, LoadConfigOptions };

package/dist/internal/loading.js

@@ -0,0 +1,9 @@
+// @bun
+import {
+  loadConfig
+} from "../shared/@outfitter/config-br341dr7.js";
+import"../shared/@outfitter/config-aje2en96.js";
+import"../shared/@outfitter/config-s4swz8m3.js";
+export {
+  loadConfig
+};

package/dist/internal/parsing.d.ts

@@ -0,0 +1,2 @@
+import { CircularExtendsError, ParseError, deepMerge, parseConfigFile } from "../shared/@outfitter/config-sp6gradd.js";
+export { parseConfigFile, deepMerge, ParseError, CircularExtendsError };

package/dist/internal/parsing.js

@@ -0,0 +1,13 @@
+// @bun
+import {
+  CircularExtendsError,
+  ParseError,
+  deepMerge,
+  parseConfigFile
+} from "../shared/@outfitter/config-s4swz8m3.js";
+export {
+  parseConfigFile,
+  deepMerge,
+  ParseError,
+  CircularExtendsError
+};

package/dist/internal/xdg.d.ts

@@ -0,0 +1,2 @@
+import { getCacheDir, getConfigDir, getDataDir, getStateDir } from "../shared/@outfitter/config-6449x3br.js";
+export { getStateDir, getDataDir, getConfigDir, getCacheDir };

package/dist/internal/xdg.js

@@ -0,0 +1,13 @@
+// @bun
+import {
+  getCacheDir,
+  getConfigDir,
+  getDataDir,
+  getStateDir
+} from "../shared/@outfitter/config-pf9xp78h.js";
+export {
+  getStateDir,
+  getDataDir,
+  getConfigDir,
+  getCacheDir
+};

package/dist/shared/@outfitter/config-6449x3br.d.ts

@@ -0,0 +1,81 @@
+/**
+* Get the XDG config directory for an application.
+*
+* Uses `XDG_CONFIG_HOME` if set, otherwise defaults to `~/.config`.
+* This follows the XDG Base Directory Specification for storing
+* user-specific configuration files.
+*
+* @param appName - Application name used as subdirectory
+* @returns Absolute path to the application's config directory
+*
+* @example
+* ```typescript
+* // With XDG_CONFIG_HOME="/custom/config"
+* getConfigDir("myapp"); // "/custom/config/myapp"
+*
+* // Without XDG_CONFIG_HOME (uses default)
+* getConfigDir("myapp"); // "/home/user/.config/myapp"
+* ```
+*/
+declare function getConfigDir(appName: string): string;
+/**
+* Get the XDG data directory for an application.
+*
+* Uses `XDG_DATA_HOME` if set, otherwise defaults to `~/.local/share`.
+* This follows the XDG Base Directory Specification for storing
+* user-specific data files (databases, generated content, etc.).
+*
+* @param appName - Application name used as subdirectory
+* @returns Absolute path to the application's data directory
+*
+* @example
+* ```typescript
+* // With XDG_DATA_HOME="/custom/data"
+* getDataDir("myapp"); // "/custom/data/myapp"
+*
+* // Without XDG_DATA_HOME (uses default)
+* getDataDir("myapp"); // "/home/user/.local/share/myapp"
+* ```
+*/
+declare function getDataDir(appName: string): string;
+/**
+* Get the XDG cache directory for an application.
+*
+* Uses `XDG_CACHE_HOME` if set, otherwise defaults to `~/.cache`.
+* This follows the XDG Base Directory Specification for storing
+* non-essential cached data that can be regenerated.
+*
+* @param appName - Application name used as subdirectory
+* @returns Absolute path to the application's cache directory
+*
+* @example
+* ```typescript
+* // With XDG_CACHE_HOME="/custom/cache"
+* getCacheDir("myapp"); // "/custom/cache/myapp"
+*
+* // Without XDG_CACHE_HOME (uses default)
+* getCacheDir("myapp"); // "/home/user/.cache/myapp"
+* ```
+*/
+declare function getCacheDir(appName: string): string;
+/**
+* Get the XDG state directory for an application.
+*
+* Uses `XDG_STATE_HOME` if set, otherwise defaults to `~/.local/state`.
+* This follows the XDG Base Directory Specification for storing
+* state data that should persist between restarts (logs, history, etc.).
+*
+* @param appName - Application name used as subdirectory
+* @returns Absolute path to the application's state directory
+*
+* @example
+* ```typescript
+* // With XDG_STATE_HOME="/custom/state"
+* getStateDir("myapp"); // "/custom/state/myapp"
+*
+* // Without XDG_STATE_HOME (uses default)
+* getStateDir("myapp"); // "/home/user/.local/state/myapp"
+* ```
+*/
+declare function getStateDir(appName: string): string;
+export { getConfigDir, getDataDir, getCacheDir, getStateDir };

package/dist/shared/@outfitter/config-7dyshh4r.d.ts

@@ -0,0 +1,105 @@
+import { CircularExtendsError, ParseError } from "./config-sp6gradd.js";
+import { NotFoundError, Result, ValidationError } from "@outfitter/contracts";
+import { ZodSchema } from "zod";
+/**
+* Options for the {@link loadConfig} function.
+*
+* @example
+* ```typescript
+* const options: LoadConfigOptions = {
+*   searchPaths: ["/etc/myapp", "/opt/myapp/config"],
+* };
+* ```
+*/
+interface LoadConfigOptions {
+	/**
+	* Custom search paths to check for config files.
+	* When provided, overrides the default XDG-based search paths.
+	* Note: `appName` is appended to each path (e.g., `"/etc/myapp"` becomes `"/etc/myapp/{appName}"`).
+	* Paths are searched in order; first match wins.
+	*/
+	searchPaths?: string[];
+}
+/**
+* Load configuration for an application from XDG-compliant paths.
+*
+* Search order (first found wins):
+* 1. Custom `searchPaths` if provided in options
+* 2. `$XDG_CONFIG_HOME/{appName}/config.{ext}`
+* 3. `~/.config/{appName}/config.{ext}`
+*
+* File format preference: `.toml` > `.yaml` > `.yml` > `.json` > `.jsonc` > `.json5`
+*
+* When called without a schema, returns the raw parsed config as `unknown`.
+* When called with a schema, returns the validated typed config.
+*
+* @param appName - Application name for XDG directory lookup
+* @returns Result containing raw config or NotFoundError/ParseError/CircularExtendsError
+*
+* @example
+* ```typescript
+* // Without schema — returns raw parsed config
+* const result = loadConfig("myapp");
+* if (result.isOk()) {
+*   const config = result.value; // type: unknown
+* }
+* ```
+*/
+declare function loadConfig(appName: string): Result<unknown, InstanceType<typeof NotFoundError> | InstanceType<typeof ParseError> | InstanceType<typeof CircularExtendsError>>;
+/**
+* Load configuration for an application from XDG-compliant paths.
+*
+* @param appName - Application name for XDG directory lookup
+* @param options - Configuration options (custom search paths)
+* @returns Result containing raw config or NotFoundError/ParseError/CircularExtendsError
+*
+* @example
+* ```typescript
+* // Without schema, with custom search paths
+* const result = loadConfig("myapp", { searchPaths: ["/etc/myapp"] });
+* ```
+*/
+declare function loadConfig(appName: string, options: LoadConfigOptions): Result<unknown, InstanceType<typeof NotFoundError> | InstanceType<typeof ParseError> | InstanceType<typeof CircularExtendsError>>;
+/**
+* Load configuration for an application from XDG-compliant paths.
+*
+* @typeParam T - The configuration type (inferred from schema)
+* @param appName - Application name for XDG directory lookup
+* @param schema - Zod schema for validation
+* @returns Result containing validated config or NotFoundError/ValidationError/ParseError/CircularExtendsError
+*
+* @example
+* ```typescript
+* import { loadConfig } from "@outfitter/config";
+* import { z } from "zod";
+*
+* const AppConfigSchema = z.object({
+*   apiKey: z.string(),
+*   timeout: z.number().default(5000),
+* });
+*
+* const result = loadConfig("myapp", AppConfigSchema);
+* if (result.isOk()) {
+*   console.log(result.value.apiKey); // typed!
+* }
+* ```
+*/
+declare function loadConfig<T>(appName: string, schema: ZodSchema<T>): Result<T, InstanceType<typeof NotFoundError> | InstanceType<typeof ValidationError> | InstanceType<typeof ParseError> | InstanceType<typeof CircularExtendsError>>;
+/**
+* Load configuration for an application from XDG-compliant paths.
+*
+* @typeParam T - The configuration type (inferred from schema)
+* @param appName - Application name for XDG directory lookup
+* @param schema - Zod schema for validation
+* @param options - Configuration options (custom search paths)
+* @returns Result containing validated config or NotFoundError/ValidationError/ParseError/CircularExtendsError
+*
+* @example
+* ```typescript
+* const result = loadConfig("myapp", AppConfigSchema, {
+*   searchPaths: ["/etc/myapp", "/opt/myapp/config"],
+* });
+* ```
+*/
+declare function loadConfig<T>(appName: string, schema: ZodSchema<T>, options: LoadConfigOptions): Result<T, InstanceType<typeof NotFoundError> | InstanceType<typeof ValidationError> | InstanceType<typeof ParseError> | InstanceType<typeof CircularExtendsError>>;
+export { LoadConfigOptions, loadConfig };

package/dist/shared/@outfitter/config-aje2en96.js

@@ -0,0 +1,71 @@
+// @bun
+import {
+  CircularExtendsError,
+  ParseError,
+  deepMerge,
+  parseConfigFile
+} from "./config-s4swz8m3.js";
+
+// packages/config/src/internal/extends.ts
+import { existsSync, readFileSync } from "fs";
+import { dirname, isAbsolute, resolve } from "path";
+import { NotFoundError, Result } from "@outfitter/contracts";
+function resolveExtendsPath(extendsValue, fromFile) {
+  if (isAbsolute(extendsValue)) {
+    return extendsValue;
+  }
+  return resolve(dirname(fromFile), extendsValue);
+}
+function loadConfigFileWithExtends(filePath, visited = new Set) {
+  const normalizedPath = resolve(filePath);
+  if (visited.has(normalizedPath)) {
+    return Result.err(new CircularExtendsError({
+      message: `Circular extends detected: ${[...visited, normalizedPath].join(" -> ")}`,
+      chain: [...visited, normalizedPath]
+    }));
+  }
+  if (!existsSync(filePath)) {
+    return Result.err(new NotFoundError({
+      message: `Config file not found: ${filePath}`,
+      resourceType: "config",
+      resourceId: filePath
+    }));
+  }
+  let content;
+  try {
+    content = readFileSync(filePath, "utf-8");
+  } catch {
+    return Result.err(new NotFoundError({
+      message: `Failed to read config file: ${filePath}`,
+      resourceType: "config",
+      resourceId: filePath
+    }));
+  }
+  const filename = filePath.split("/").pop() ?? "config";
+  const parseResult = parseConfigFile(content, filename);
+  if (parseResult.isErr()) {
+    return Result.err(parseResult.error);
+  }
+  const parsed = parseResult.unwrap();
+  const extendsValue = parsed["extends"];
+  if (extendsValue === undefined) {
+    return Result.ok(parsed);
+  }
+  if (typeof extendsValue !== "string") {
+    return Result.err(new ParseError({
+      message: `Invalid "extends" value in ${filePath}: expected string, got ${typeof extendsValue}`,
+      filename: filePath
+    }));
+  }
+  visited.add(normalizedPath);
+  const extendsPath = resolveExtendsPath(extendsValue, filePath);
+  const baseResult = loadConfigFileWithExtends(extendsPath, visited);
+  if (baseResult.isErr()) {
+    return Result.err(baseResult.error);
+  }
+  const baseConfig = baseResult.unwrap();
+  const { extends: __, ...currentConfig } = parsed;
+  return Result.ok(deepMerge(baseConfig, currentConfig));
+}
+
+export { resolveExtendsPath, loadConfigFileWithExtends };

package/dist/shared/@outfitter/config-br341dr7.js

@@ -0,0 +1,87 @@
+// @bun
+import {
+  loadConfigFileWithExtends
+} from "./config-aje2en96.js";
+
+// packages/config/src/internal/loading.ts
+import { existsSync } from "fs";
+import { join } from "path";
+import {
+  formatZodIssues,
+  NotFoundError,
+  Result,
+  ValidationError
+} from "@outfitter/contracts";
+var CONFIG_EXTENSIONS = ["toml", "yaml", "yml", "json", "jsonc", "json5"];
+function findConfigFile(dir) {
+  for (const ext of CONFIG_EXTENSIONS) {
+    const filePath = join(dir, `config.${ext}`);
+    if (existsSync(filePath)) {
+      return filePath;
+    }
+  }
+  return;
+}
+function getDefaultSearchPaths(appName) {
+  const xdgConfigHome = process.env["XDG_CONFIG_HOME"];
+  const home = process.env["HOME"] ?? "";
+  const defaultConfigPath = join(home, ".config", appName);
+  if (xdgConfigHome) {
+    const xdgPath = join(xdgConfigHome, appName);
+    if (xdgPath !== defaultConfigPath) {
+      return [xdgPath, defaultConfigPath];
+    }
+  }
+  return [defaultConfigPath];
+}
+function isZodSchema(value) {
+  return typeof value === "object" && value !== null && "safeParse" in value && typeof value["safeParse"] === "function";
+}
+function loadConfig(appName, schemaOrOptions, maybeOptions) {
+  let schema;
+  let options;
+  if (schemaOrOptions !== undefined) {
+    if (isZodSchema(schemaOrOptions)) {
+      schema = schemaOrOptions;
+      options = maybeOptions;
+    } else {
+      options = schemaOrOptions;
+    }
+  }
+  const searchPaths = options?.searchPaths ? options.searchPaths.map((p) => join(p, appName)) : getDefaultSearchPaths(appName);
+  let configFilePath;
+  for (const searchPath of searchPaths) {
+    const found = findConfigFile(searchPath);
+    if (found) {
+      configFilePath = found;
+      break;
+    }
+  }
+  if (!configFilePath) {
+    return Result.err(new NotFoundError({
+      message: `Configuration file not found for ${appName}`,
+      resourceType: "config",
+      resourceId: appName
+    }));
+  }
+  const loadResult = loadConfigFileWithExtends(configFilePath);
+  if (loadResult.isErr()) {
+    return Result.err(loadResult.error);
+  }
+  const parsed = loadResult.unwrap();
+  if (!schema) {
+    return Result.ok(parsed);
+  }
+  const validateResult = schema.safeParse(parsed);
+  if (!validateResult.success) {
+    const fullMessage = formatZodIssues(validateResult.error.issues);
+    const firstPath = validateResult.error.issues[0]?.path?.join(".");
+    return Result.err(new ValidationError({
+      message: fullMessage,
+      ...firstPath ? { field: firstPath } : {}
+    }));
+  }
+  return Result.ok(validateResult.data);
+}
+
+export { loadConfig };

package/dist/shared/@outfitter/config-pf9xp78h.js

@@ -0,0 +1,29 @@
+// @bun
+// packages/config/src/internal/xdg.ts
+import { join } from "path";
+function getConfigDir(appName) {
+  const xdgConfigHome = process.env["XDG_CONFIG_HOME"];
+  const home = process.env["HOME"] ?? "";
+  const baseDir = xdgConfigHome ?? join(home, ".config");
+  return join(baseDir, appName);
+}
+function getDataDir(appName) {
+  const xdgDataHome = process.env["XDG_DATA_HOME"];
+  const home = process.env["HOME"] ?? "";
+  const baseDir = xdgDataHome ?? join(home, ".local", "share");
+  return join(baseDir, appName);
+}
+function getCacheDir(appName) {
+  const xdgCacheHome = process.env["XDG_CACHE_HOME"];
+  const home = process.env["HOME"] ?? "";
+  const baseDir = xdgCacheHome ?? join(home, ".cache");
+  return join(baseDir, appName);
+}
+function getStateDir(appName) {
+  const xdgStateHome = process.env["XDG_STATE_HOME"];
+  const home = process.env["HOME"] ?? "";
+  const baseDir = xdgStateHome ?? join(home, ".local", "state");
+  return join(baseDir, appName);
+}
+
+export { getConfigDir, getDataDir, getCacheDir, getStateDir };

package/dist/shared/@outfitter/config-s4swz8m3.js

@@ -0,0 +1,97 @@
+// @bun
+// packages/config/src/internal/parsing.ts
+import { Result, TaggedError } from "@outfitter/contracts";
+import { parse as parseToml } from "smol-toml";
+import { parse as parseYaml } from "yaml";
+var ParseErrorBase = TaggedError("ParseError")();
+
+class ParseError extends ParseErrorBase {
+  category = "validation";
+}
+var CircularExtendsErrorBase = TaggedError("CircularExtendsError")();
+
+class CircularExtendsError extends CircularExtendsErrorBase {
+  category = "validation";
+}
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+  if (Array.isArray(value)) {
+    return false;
+  }
+  return true;
+}
+function deepMerge(target, source) {
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    const sourceValue = source[key];
+    const targetValue = result[key];
+    if (sourceValue === undefined) {
+      continue;
+    }
+    if (sourceValue === null) {
+      result[key] = null;
+      continue;
+    }
+    if (Array.isArray(sourceValue)) {
+      result[key] = sourceValue;
+      continue;
+    }
+    if (isPlainObject(sourceValue) && isPlainObject(targetValue)) {
+      result[key] = deepMerge(targetValue, sourceValue);
+      continue;
+    }
+    result[key] = sourceValue;
+  }
+  return result;
+}
+function getExtension(filename) {
+  const lastDot = filename.lastIndexOf(".");
+  if (lastDot === -1) {
+    return "";
+  }
+  return filename.slice(lastDot + 1).toLowerCase();
+}
+function parseConfigFile(content, filename) {
+  const ext = getExtension(filename);
+  try {
+    switch (ext) {
+      case "toml": {
+        const parsed = parseToml(content);
+        return Result.ok(parsed);
+      }
+      case "yaml":
+      case "yml": {
+        const parsed = parseYaml(content, { merge: true });
+        if (parsed === null || typeof parsed !== "object") {
+          return Result.ok({});
+        }
+        return Result.ok(parsed);
+      }
+      case "json": {
+        const parsed = JSON.parse(content);
+        return Result.ok(parsed);
+      }
+      case "jsonc":
+      case "json5": {
+        const parsed = Bun.JSON5.parse(content);
+        return Result.ok(parsed);
+      }
+      default: {
+        return Result.err(new ParseError({
+          message: `Unsupported config file extension: .${ext}`,
+          filename
+        }));
+      }
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown parse error";
+    return Result.err(new ParseError({
+      message: `Failed to parse ${filename}: ${message}`,
+      filename
+    }));
+  }
+}
+
+export { ParseError, CircularExtendsError, deepMerge, parseConfigFile };

package/dist/shared/@outfitter/config-sp6gradd.d.ts

@@ -0,0 +1,129 @@
+import { TaggedErrorClass } from "@outfitter/contracts";
+import { Result } from "@outfitter/contracts";
+type ParseErrorFields = {
+	/** Human-readable error message describing the parse failure */
+	message: string;
+	/** Name of the file that failed to parse */
+	filename: string;
+	/** Line number where the error occurred (if available) */
+	line?: number;
+	/** Column number where the error occurred (if available) */
+	column?: number;
+};
+declare const ParseErrorBase: TaggedErrorClass<"ParseError", ParseErrorFields>;
+/**
+* Error thrown when a configuration file cannot be parsed.
+*
+* Contains details about the parse failure including the filename
+* and optionally the line/column where the error occurred.
+*
+* @example
+* ```typescript
+* const result = parseConfigFile("invalid toml [", "config.toml");
+* if (result.isErr() && result.error._tag === "ParseError") {
+*   console.error(`Parse error in ${result.error.filename}: ${result.error.message}`);
+* }
+* ```
+*/
+declare class ParseError extends ParseErrorBase {
+	readonly category: "validation";
+}
+type CircularExtendsErrorFields = {
+	/** Human-readable error message */
+	message: string;
+	/** The config file paths that form the circular reference */
+	chain: string[];
+};
+declare const CircularExtendsErrorBase: TaggedErrorClass<"CircularExtendsError", CircularExtendsErrorFields>;
+/**
+* Error thrown when a circular extends reference is detected.
+*/
+declare class CircularExtendsError extends CircularExtendsErrorBase {
+	readonly category: "validation";
+}
+/**
+* Deep merge two objects with configurable merge semantics.
+*
+* Merge behavior:
+* - Recursively merges nested plain objects
+* - Arrays are replaced (not concatenated)
+* - `null` explicitly replaces the target value
+* - `undefined` is skipped (does not override)
+*
+* @typeParam T - The type of the target object
+* @param target - Base object to merge into (not mutated)
+* @param source - Object with values to merge
+* @returns New object with merged values
+*
+* @example
+* ```typescript
+* const defaults = { server: { port: 3000, host: "localhost" } };
+* const overrides = { server: { port: 8080 } };
+*
+* const merged = deepMerge(defaults, overrides);
+* // { server: { port: 8080, host: "localhost" } }
+* ```
+*
+* @example
+* ```typescript
+* // Arrays replace, not merge
+* const target = { tags: ["a", "b"] };
+* const source = { tags: ["c"] };
+* deepMerge(target, source); // { tags: ["c"] }
+*
+* // undefined is skipped
+* const base = { a: 1, b: 2 };
+* deepMerge(base, { a: undefined, b: 3 }); // { a: 1, b: 3 }
+*
+* // null explicitly replaces
+* deepMerge(base, { a: null }); // { a: null, b: 2 }
+* ```
+*/
+declare function deepMerge<T extends object>(target: T, source: Partial<T>): T;
+/**
+* Parse configuration file content based on filename extension.
+*
+* Supports multiple formats:
+* - `.toml` - Parsed with smol-toml (preferred for config)
+* - `.yaml`, `.yml` - Parsed with yaml (merge key support enabled)
+* - `.json` - Parsed with strict JSON.parse
+* - `.jsonc` - Parsed with json5 compatibility (comments/trailing commas)
+* - `.json5` - Parsed with json5 (comments and trailing commas allowed)
+*
+* @param content - Raw file content to parse
+* @param filename - Filename used to determine format (by extension)
+* @returns Result containing parsed object or ParseError
+*
+* @example
+* ```typescript
+* const toml = `
+* [server]
+* port = 3000
+* host = "localhost"
+* `;
+*
+* const result = parseConfigFile(toml, "config.toml");
+* if (result.isOk()) {
+*   console.log(result.value.server.port); // 3000
+* }
+* ```
+*
+* @example
+* ```typescript
+* // YAML with anchors/aliases
+* const yaml = `
+* defaults: &defaults
+*   timeout: 5000
+* server:
+*   <<: *defaults
+*   port: 3000
+* `;
+*
+* const result = parseConfigFile(yaml, "config.yaml");
+* if (result.isOk()) {
+*   console.log(result.value.server.timeout); // 5000
+* }
+* ```
+*/
+declare function parseConfigFile(content: string, filename: string): Result<Record<string, unknown>, InstanceType<typeof ParseError>>;
+export { ParseError, CircularExtendsError, deepMerge, parseConfigFile };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outfitter/config",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "XDG-compliant config loading with schema validation for Outfitter",
   "keywords": [
     "config",
@@ -46,7 +46,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "cd ../.. && bunup --filter @outfitter/config",
+    "build": "cd ../.. && bash ./scripts/run-bunup-with-lock.sh bunup --filter @outfitter/config",
     "lint": "oxlint ./src",
     "lint:fix": "oxlint --fix ./src",
     "test": "bun test",
@@ -55,8 +55,8 @@
     "prepublishOnly": "bun ../../scripts/check-publish-manifest.ts"
   },
   "dependencies": {
-    "@outfitter/contracts": "0.4.2",
-    "@outfitter/types": "0.2.4",
+    "@outfitter/contracts": "0.5.0",
+    "@outfitter/types": "0.2.5",
     "smol-toml": "^1.6.0",
     "yaml": "^2.8.2",
     "zod": "^4.3.5"