@outfitter/config 0.1.0 → 0.3.0

package/README.md

@@ -68,7 +68,7 @@ if (result.isOk()) {
 2. `$XDG_CONFIG_HOME/{appName}/config.{ext}`
 3. `~/.config/{appName}/config.{ext}`
 
-**File Format Preference:** `.toml` > `.yaml` > `.yml` > `.json` > `.json5`
+**File Format Preference:** `.toml` > `.yaml` > `.yml` > `.json` > `.jsonc` > `.json5`
 
 **Returns:** `Result<T, NotFoundError | ValidationError | ParseError>`
 
@@ -227,6 +227,61 @@ class ParseError {
 
 ---
 
+## Environment Profiles
+
+Unified environment detection for consistent defaults across all Outfitter packages.
+
+### `getEnvironment()`
+
+Reads `OUTFITTER_ENV` and returns the current profile. Falls back to `"production"` when unset or invalid.
+
+```typescript
+import { getEnvironment } from "@outfitter/config";
+
+const env = getEnvironment();
+// "development" | "production" | "test"
+```
+
+### `getEnvironmentDefaults(env)`
+
+Returns profile-specific defaults for an environment.
+
+```typescript
+import { getEnvironmentDefaults } from "@outfitter/config";
+
+const defaults = getEnvironmentDefaults("development");
+// { logLevel: "debug", verbose: true, errorDetail: "full" }
+
+const prodDefaults = getEnvironmentDefaults("production");
+// { logLevel: null, verbose: false, errorDetail: "message" }
+```
+
+| Setting | `development` | `production` | `test` |
+|---------|--------------|-------------|--------|
+| logLevel | `"debug"` | `null` | `null` |
+| verbose | `true` | `false` | `false` |
+| errorDetail | `"full"` | `"message"` | `"full"` |
+
+### Types
+
+#### `OutfitterEnv`
+
+```typescript
+type OutfitterEnv = "development" | "production" | "test";
+```
+
+#### `EnvironmentDefaults`
+
+```typescript
+interface EnvironmentDefaults {
+  logLevel: "debug" | "info" | "warn" | "error" | null;
+  verbose: boolean;
+  errorDetail: "full" | "message";
+}
+```
+
+---
+
 ## XDG Base Directory Specification
 
 This package follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) for locating configuration files.
@@ -267,6 +322,7 @@ Higher precedence sources override lower ones. Nested objects are deep-merged.
 | `.toml` | smol-toml | Preferred for configuration |
 | `.yaml`, `.yml` | yaml | YAML anchors/aliases supported |
 | `.json` | JSON.parse | Strict parsing |
+| `.jsonc` | json5 | JSON with comments and trailing commas |
 | `.json5` | json5 | Comments and trailing commas allowed |
 
 ---

package/dist/index.d.ts

@@ -1,3 +1,92 @@
+/**
+* Unified environment profiles for Outfitter packages.
+*
+* Provides a shared "environment" concept that cascades defaults
+* across all Outfitter packages. The environment is determined by
+* the `OUTFITTER_ENV` environment variable, falling back to
+* `"production"` when unset or invalid.
+*
+* @example
+* ```typescript
+* import { getEnvironment, getEnvironmentDefaults } from "@outfitter/config";
+*
+* const env = getEnvironment(); // "development" | "production" | "test"
+* const defaults = getEnvironmentDefaults(env);
+*
+* if (defaults.verbose) {
+*   console.log("Verbose mode enabled");
+* }
+* ```
+*
+* @module
+*/
+/**
+* Valid Outfitter environment names.
+*
+* - `"development"` — Local development with verbose output and debug logging
+* - `"production"` — Production deployments with minimal output
+* - `"test"` — Test runs with full error detail but no logging
+*/
+type OutfitterEnv = "development" | "production" | "test";
+/**
+* Profile-specific defaults for an environment.
+*
+* These defaults provide sensible starting values that individual
+* packages can override or extend.
+*/
+interface EnvironmentDefaults {
+	/** Default log level. `null` means logging is disabled by default. */
+	logLevel: "debug" | "info" | "warn" | "error" | null;
+	/** Whether verbose output is enabled by default. */
+	verbose: boolean;
+	/** How much error detail to include in output. */
+	errorDetail: "full" | "message";
+}
+/**
+* Determine the current Outfitter environment.
+*
+* Reads the `OUTFITTER_ENV` environment variable. If set to a valid
+* value (`"development"`, `"production"`, or `"test"`), returns that
+* value. Otherwise falls back to `"production"`.
+*
+* @returns The current environment
+*
+* @example
+* ```typescript
+* // With OUTFITTER_ENV=development
+* getEnvironment(); // "development"
+*
+* // With OUTFITTER_ENV unset or invalid
+* getEnvironment(); // "production"
+* ```
+*/
+declare function getEnvironment(): OutfitterEnv;
+/**
+* Get the default settings for an environment profile.
+*
+* Returns a shallow copy of the defaults for the given environment.
+* These defaults are intended as starting values that individual
+* packages can override via their own configuration.
+*
+* | Setting | `development` | `production` | `test` |
+* |---------|--------------|-------------|--------|
+* | logLevel | `"debug"` | `null` | `null` |
+* | verbose | `true` | `false` | `false` |
+* | errorDetail | `"full"` | `"message"` | `"full"` |
+*
+* @param env - The environment to get defaults for
+* @returns Profile-specific default settings
+*
+* @example
+* ```typescript
+* const defaults = getEnvironmentDefaults("development");
+* // { logLevel: "debug", verbose: true, errorDetail: "full" }
+*
+* const prodDefaults = getEnvironmentDefaults("production");
+* // { logLevel: null, verbose: false, errorDetail: "message" }
+* ```
+*/
+declare function getEnvironmentDefaults(env: OutfitterEnv): EnvironmentDefaults;
 import { z } from "zod";
 /**
 * Port number schema (1-65535) with string-to-number coercion.
@@ -310,6 +399,7 @@ declare function deepMerge<T extends object>(target: T, source: Partial<T>): T;
 * - `.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
@@ -438,7 +528,7 @@ interface LoadConfigOptions {
 * 2. `$XDG_CONFIG_HOME/{appName}/config.{ext}`
 * 3. `~/.config/{appName}/config.{ext}`
 *
-* File format preference: `.toml` > `.yaml` > `.yml` > `.json` > `.json5`
+* 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
@@ -508,4 +598,4 @@ declare function loadConfig<T>(appName: string, schema: ZodSchema<T>, options?:
 * ```
 */
 declare function mapEnvToConfig<T>(prefix: string, _schema?: ZodSchema<T>): Partial<T>;
-export { resolveConfig, portSchema, parseEnv, parseConfigFile, optionalBooleanSchema, mapEnvToConfig, loadConfig, getStateDir, getEnvBoolean, getDataDir, getConfigDir, getCacheDir, env, deepMerge, booleanSchema, ParseError, LoadConfigOptions, Env, ConfigSources, CircularExtendsError };
+export { resolveConfig, portSchema, parseEnv, parseConfigFile, optionalBooleanSchema, mapEnvToConfig, loadConfig, getStateDir, getEnvironmentDefaults, getEnvironment, getEnvBoolean, getDataDir, getConfigDir, getCacheDir, env, deepMerge, booleanSchema, ParseError, OutfitterEnv, LoadConfigOptions, EnvironmentDefaults, Env, ConfigSources, CircularExtendsError };

package/dist/index.js

@@ -8034,6 +8034,39 @@ var require_public_api = __commonJS((exports) => {
   exports.stringify = stringify2;
 });
 
+// src/environment.ts
+var VALID_ENVIRONMENTS = new Set([
+  "development",
+  "production",
+  "test"
+]);
+var ENVIRONMENT_DEFAULTS = {
+  development: {
+    logLevel: "debug",
+    verbose: true,
+    errorDetail: "full"
+  },
+  production: {
+    logLevel: null,
+    verbose: false,
+    errorDetail: "message"
+  },
+  test: {
+    logLevel: null,
+    verbose: false,
+    errorDetail: "full"
+  }
+};
+function getEnvironment() {
+  const value = process.env["OUTFITTER_ENV"];
+  if (value !== undefined && VALID_ENVIRONMENTS.has(value)) {
+    return value;
+  }
+  return "production";
+}
+function getEnvironmentDefaults(env) {
+  return { ...ENVIRONMENT_DEFAULTS[env] };
+}
 // src/env.ts
 import { z } from "zod";
 var portSchema = z.string().regex(/^\d+$/).transform(Number).pipe(z.number().int().positive().max(65535));
@@ -9159,6 +9192,7 @@ function parseConfigFile(content, filename) {
         const parsed = JSON.parse(content);
         return Result.ok(parsed);
       }
+      case "jsonc":
       case "json5": {
         const parsed = import_json5.default.parse(content);
         return Result.ok(parsed);
@@ -9206,7 +9240,7 @@ function resolveConfig(schema, sources) {
   }
   return Result.ok(parseResult.data);
 }
-var CONFIG_EXTENSIONS = ["toml", "yaml", "yml", "json", "json5"];
+var CONFIG_EXTENSIONS = ["toml", "yaml", "yml", "json", "jsonc", "json5"];
 function findConfigFile(dir) {
   for (const ext of CONFIG_EXTENSIONS) {
     const filePath = join(dir, `config.${ext}`);
@@ -9355,6 +9389,8 @@ export {
   mapEnvToConfig,
   loadConfig,
   getStateDir,
+  getEnvironmentDefaults,
+  getEnvironment,
   getEnvBoolean,
   getDataDir,
   getConfigDir,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@outfitter/config",
   "description": "XDG-compliant config loading with schema validation for Outfitter",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "files": [
     "dist"
@@ -9,12 +9,24 @@
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
+    "./environment": {
+      "import": {
+        "types": "./dist/environment.d.ts",
+        "default": "./dist/environment.js"
+      }
+    },
     ".": {
       "import": {
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
       }
     },
+    "./env": {
+      "import": {
+        "types": "./dist/env.d.ts",
+        "default": "./dist/env.js"
+      }
+    },
     "./package.json": "./package.json"
   },
   "sideEffects": false,
@@ -27,8 +39,8 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@outfitter/contracts": "0.1.0",
-    "@outfitter/types": "0.1.0",
+    "@outfitter/contracts": "0.2.0",
+    "@outfitter/types": "0.2.0",
     "zod": "^4.3.5"
   },
   "devDependencies": {