@ontrails/config 1.0.0-beta.12

package/src/app-config.ts

@@ -0,0 +1,307 @@
+/**
+ * App config factory — declare a config contract once, discover and validate at runtime.
+ */
+
+import { dirname, join } from 'node:path';
+
+import { NotFoundError, Result, ValidationError } from '@ontrails/core';
+import type { z } from 'zod';
+
+import type { CheckResult } from './doctor.js';
+import { checkConfig } from './doctor.js';
+import type { FieldDescription } from './describe.js';
+import { describeConfig } from './describe.js';
+import type { ExplainConfigOptions, ProvenanceEntry } from './explain.js';
+import { explainConfig } from './explain.js';
+import type { ConfigRef } from './ref.js';
+import { configRef } from './ref.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Supported config file formats. */
+export type ConfigFormat = 'toml' | 'json' | 'jsonc' | 'yaml';
+
+/** Options for creating an app config. */
+export interface AppConfigOptions<T extends z.ZodType> {
+  readonly schema: T;
+  readonly formats?: readonly ConfigFormat[];
+  readonly dotfile?: boolean;
+}
+
+/** Options for resolving (discovering + parsing) a config file. */
+export interface ResolveOptions {
+  /** Working directory for discovery. Defaults to `process.cwd()`. */
+  readonly cwd?: string;
+  /** Explicit file path — skips discovery when provided. */
+  readonly path?: string;
+}
+
+/** Options for the `explain()` method on AppConfig, excluding schema. */
+export type AppConfigExplainOptions = Omit<
+  ExplainConfigOptions<z.ZodType>,
+  'schema'
+>;
+
+/** The resolved config contract returned by `appConfig()`. */
+export interface AppConfig<T extends z.ZodType> {
+  readonly name: string;
+  readonly schema: T;
+  readonly formats: readonly ConfigFormat[];
+  readonly dotfile: boolean;
+  resolve(options?: ResolveOptions): Promise<Result<z.infer<T>, Error>>;
+
+  /** Describe all fields in the schema without needing values. */
+  describe(): readonly FieldDescription[];
+
+  /** Check a config object against the schema and return diagnostics. */
+  check(
+    values: Record<string, unknown>,
+    options?: { readonly env?: Record<string, string | undefined> }
+  ): CheckResult;
+
+  /** Show which source won for each config field. */
+  explain(options: AppConfigExplainOptions): readonly ProvenanceEntry[];
+
+  /** Create a lazy reference to a config field for use as a trail input default. */
+  ref(fieldPath: string): ConfigRef;
+}
+
+// ---------------------------------------------------------------------------
+// Default values
+// ---------------------------------------------------------------------------
+
+const DEFAULT_FORMATS: readonly ConfigFormat[] = ['toml', 'json', 'yaml'];
+
+// ---------------------------------------------------------------------------
+// Internal helpers (defined before consumers — no-use-before-define)
+// ---------------------------------------------------------------------------
+
+/** Build the config filename for a given format. */
+const configFileName = (
+  name: string,
+  format: ConfigFormat,
+  dotfile: boolean
+): string => (dotfile ? `.${name}rc.${format}` : `${name}.config.${format}`);
+
+/** Check whether a file exists at the given path. */
+const fileExists = (filePath: string): Promise<boolean> =>
+  Bun.file(filePath).exists();
+
+/** Known config suffixes, ordered to avoid `.json` matching `.jsonc`. */
+const FORMAT_SUFFIXES: readonly [ConfigFormat, `.${string}`][] = [
+  ['jsonc', '.jsonc'],
+  ['json', '.json'],
+  ['toml', '.toml'],
+  ['yaml', '.yaml'],
+];
+
+/** Detect the declared config format from a file path. */
+const detectFormat = (filePath: string): ConfigFormat | undefined => {
+  for (const [format, suffix] of FORMAT_SUFFIXES) {
+    if (filePath.endsWith(suffix)) {
+      return format;
+    }
+  }
+  return undefined;
+};
+
+/** Parse config file text with Bun's native format parsers. */
+const parseConfigText = (
+  filePath: string,
+  text: string
+): Result<unknown, Error> => {
+  const format = detectFormat(filePath);
+
+  try {
+    switch (format) {
+      case 'json': {
+        return Result.ok(JSON.parse(text));
+      }
+      case 'jsonc': {
+        return Result.ok(Bun.JSONC.parse(text));
+      }
+      case 'toml': {
+        return Result.ok(Bun.TOML.parse(text));
+      }
+      case 'yaml': {
+        return Result.ok(Bun.YAML.parse(text));
+      }
+      default: {
+        return Result.err(
+          new ValidationError(`Unsupported config file format: ${filePath}`, {
+            context: { path: filePath },
+          })
+        );
+      }
+    }
+  } catch (error) {
+    return Result.err(
+      new ValidationError(`Failed to parse config file: ${filePath}`, {
+        cause: error instanceof Error ? error : new Error(String(error)),
+        context: { path: filePath },
+      })
+    );
+  }
+};
+
+/** Read and parse a config file, always reflecting the latest on-disk content. */
+const readConfigFile = async (
+  filePath: string
+): Promise<Result<unknown, Error>> => {
+  const exists = await fileExists(filePath);
+  if (!exists) {
+    return Result.err(
+      new NotFoundError(`Config file not found: ${filePath}`, {
+        context: { path: filePath },
+      })
+    );
+  }
+
+  const text = await Bun.file(filePath).text();
+  return parseConfigText(filePath, text);
+};
+
+/** Validate parsed data against a Zod schema. */
+const validateConfig = <T extends z.ZodType>(
+  schema: T,
+  data: unknown,
+  filePath: string
+): Result<z.infer<T>, Error> => {
+  const parsed = schema.safeParse(data);
+  if (parsed.success) {
+    return Result.ok(parsed.data as z.infer<T>);
+  }
+  return Result.err(
+    new ValidationError(`Config validation failed: ${filePath}`, {
+      context: {
+        issues: parsed.error.issues,
+        path: filePath,
+      },
+    })
+  );
+};
+
+/** Check all format candidates in a single directory. */
+const findInDir = async (
+  dir: string,
+  name: string,
+  formats: readonly ConfigFormat[],
+  dotfile: boolean
+): Promise<string | undefined> => {
+  for (const format of formats) {
+    const candidate = join(dir, configFileName(name, format, dotfile));
+    if (await fileExists(candidate)) {
+      return candidate;
+    }
+  }
+  return undefined;
+};
+
+/** Walk up from `startDir` looking for any matching config filename. */
+const discoverConfigFile = async (
+  name: string,
+  formats: readonly ConfigFormat[],
+  dotfile: boolean,
+  startDir: string
+): Promise<string | undefined> => {
+  let dir = startDir;
+
+  for (let depth = 0; depth < 64; depth += 1) {
+    const found = await findInDir(dir, name, formats, dotfile);
+    if (found !== undefined) {
+      return found;
+    }
+    const parent = dirname(dir);
+    // Reached filesystem root
+    if (parent === dir) {
+      break;
+    }
+    dir = parent;
+  }
+
+  return undefined;
+};
+
+/** Resolve a config file — either from an explicit path or via discovery. */
+const resolveConfig = async <T extends z.ZodType>(
+  name: string,
+  schema: T,
+  formats: readonly ConfigFormat[],
+  dotfile: boolean,
+  options?: ResolveOptions
+): Promise<Result<z.infer<T>, Error>> => {
+  const filePath =
+    options?.path ??
+    (await discoverConfigFile(
+      name,
+      formats,
+      dotfile,
+      options?.cwd ?? process.cwd()
+    ));
+
+  if (filePath === undefined) {
+    return Result.err(
+      new NotFoundError(`No config file found for "${name}"`, {
+        context: { dotfile, formats: [...formats], name },
+      })
+    );
+  }
+
+  const readResult = await readConfigFile(filePath);
+  if (readResult.isErr()) {
+    return readResult;
+  }
+
+  return validateConfig(schema, readResult.value, filePath);
+};
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Declare a config contract for an app.
+ *
+ * The returned `AppConfig` exposes `resolve()` to discover, parse, and validate
+ * a config file matching the app name and format conventions.
+ *
+ * @example
+ * ```ts
+ * const config = appConfig('myapp', {
+ *   schema: z.object({
+ *     output: z.string().default('./output'),
+ *     verbose: z.boolean().default(false),
+ *   }),
+ * });
+ *
+ * const result = await config.resolve();
+ * if (result.isOk()) console.log(result.value.output);
+ * ```
+ */
+export const appConfig = <T extends z.ZodType>(
+  name: string,
+  options: AppConfigOptions<T>
+): AppConfig<T> => {
+  const formats = options.formats ?? DEFAULT_FORMATS;
+  const dotfile = options.dotfile ?? false;
+
+  const { schema } = options;
+
+  return {
+    check: (values, checkOpts) => checkConfig(schema, values, checkOpts),
+    describe: () =>
+      describeConfig(
+        schema as unknown as z.ZodObject<Record<string, z.ZodType>>
+      ),
+    dotfile,
+    explain: (explainOpts) => explainConfig({ ...explainOpts, schema }),
+    formats,
+    name,
+    ref: (fieldPath) => configRef(fieldPath),
+    resolve: (resolveOptions?: ResolveOptions) =>
+      resolveConfig(name, schema, formats, dotfile, resolveOptions),
+    schema,
+  };
+};

package/src/collect.ts

@@ -0,0 +1,118 @@
+import { globalRegistry } from 'zod';
+import type { z } from 'zod';
+
+import type { ConfigFieldMeta } from './extensions.js';
+import { isZodObject, unwrapToBase } from './zod-utils.js';
+
+/** Config meta keys we look for in Zod registry entries. */
+const META_EXTRACTORS: readonly {
+  test: (raw: Record<string, unknown>) => boolean;
+  extract: (raw: Record<string, unknown>) => Partial<ConfigFieldMeta>;
+}[] = [
+  {
+    extract: (r) => ({ env: r['env'] as string }),
+    test: (r) => typeof r['env'] === 'string',
+  },
+  {
+    extract: () => ({ secret: true }),
+    test: (r) => r['secret'] === true,
+  },
+  {
+    extract: (r) => ({ deprecated: r['deprecationMessage'] as string }),
+    test: (r) => typeof r['deprecationMessage'] === 'string',
+  },
+];
+
+/**
+ * Pick only `ConfigFieldMeta` keys from a raw registry entry.
+ * Uses a lookup table to stay under the max-statements limit.
+ */
+const pickConfigMeta = (
+  raw: Record<string, unknown> | undefined
+): ConfigFieldMeta | undefined => {
+  if (!raw) {
+    return undefined;
+  }
+
+  const parts = META_EXTRACTORS.filter((e) => e.test(raw)).map((e) =>
+    e.extract(raw)
+  );
+  return parts.length > 0
+    ? (Object.assign({}, ...parts) as ConfigFieldMeta)
+    : undefined;
+};
+
+/**
+ * Extract `ConfigFieldMeta` from a schema, unwrapping through
+ * `.default()`, `.optional()`, `.nullable()` wrappers as needed.
+ */
+const extractConfigMeta = (schema: z.ZodType): ConfigFieldMeta | undefined => {
+  let current: z.ZodType | undefined = schema;
+
+  while (current) {
+    const meta = pickConfigMeta(globalRegistry.get(current));
+    if (meta) {
+      return meta;
+    }
+
+    const def = current.def as unknown as Record<string, unknown>;
+    current = def['innerType'] as z.ZodType | undefined;
+  }
+
+  return undefined;
+};
+
+/** Entry in the iterative work queue for schema walking. */
+interface WalkEntry {
+  readonly schema: z.ZodObject<Record<string, z.ZodType>>;
+  readonly prefix: string;
+}
+
+/** Process one level of an object schema, queuing nested objects. */
+const walkObjectShape = (
+  schema: z.ZodObject<Record<string, z.ZodType>>,
+  prefix: string,
+  result: Map<string, ConfigFieldMeta>,
+  queue: WalkEntry[]
+): void => {
+  const shape = schema.shape as Record<string, z.ZodType>;
+
+  for (const [key, fieldSchema] of Object.entries(shape)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+
+    if (isZodObject(fieldSchema)) {
+      queue.push({
+        prefix: path,
+        schema: unwrapToBase(fieldSchema) as z.ZodObject<
+          Record<string, z.ZodType>
+        >,
+      });
+    } else {
+      const meta = extractConfigMeta(fieldSchema);
+      if (meta) {
+        result.set(path, meta);
+      }
+    }
+  }
+};
+
+/**
+ * Walk a Zod object schema and collect `ConfigFieldMeta` for each field.
+ *
+ * Handles unwrapping `.default()`, `.optional()`, `.nullable()` wrappers
+ * that don't carry inner metadata forward. Recurses into nested `ZodObject`
+ * fields using dot-separated paths.
+ */
+export const collectConfigMeta = (
+  schema: z.ZodObject<Record<string, z.ZodType>>,
+  prefix = ''
+): Map<string, ConfigFieldMeta> => {
+  const result = new Map<string, ConfigFieldMeta>();
+  const queue: WalkEntry[] = [{ prefix, schema }];
+
+  for (let entry = queue.pop(); entry; entry = queue.pop()) {
+    walkObjectShape(entry.schema, entry.prefix, result, queue);
+  }
+
+  return result;
+};

package/src/compose.ts

@@ -0,0 +1,46 @@
+/**
+ * Config composition utilities for services.
+ *
+ * Collects config schemas from service declarations so they can be
+ * composed into a unified config structure via `defineConfig`.
+ */
+
+import type { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A service config schema entry extracted from a service declaration. */
+export interface ServiceConfigEntry {
+  readonly serviceId: string;
+  readonly schema: z.ZodType;
+}
+
+/** Minimal shape needed to extract config from a service-like object. */
+interface ServiceWithOptionalConfig {
+  readonly id: string;
+  readonly config?: z.ZodType | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Collect config schemas from services that declare them.
+ *
+ * Returns entries keyed by service ID for composition into `defineConfig`.
+ * Services without a `config` schema are excluded.
+ */
+export const collectServiceConfigs = (
+  services: readonly ServiceWithOptionalConfig[]
+): ServiceConfigEntry[] =>
+  services
+    .filter(
+      (
+        svc
+      ): svc is ServiceWithOptionalConfig & { readonly config: z.ZodType } =>
+        svc.config !== undefined
+    )
+    .map((svc) => ({ schema: svc.config, serviceId: svc.id }));

package/src/config-layer.ts

@@ -0,0 +1,15 @@
+/**
+ * Config layer — attaches resolved config to the execution context.
+ *
+ * For v1, the layer is a pass-through: config resolution happens at
+ * bootstrap time and the service pipeline (TRL-91) injects the resolved
+ * config before any trail runs. The layer reserves a named slot so
+ * future versions can add per-trail config overrides or validation.
+ */
+import type { Layer } from '@ontrails/core';
+
+export const configLayer: Layer = {
+  description: 'Ensures resolved config is available in the execution context',
+  name: 'config',
+  wrap: (_trail, impl) => (input, ctx) => impl(input, ctx),
+};

package/src/config-service.ts

@@ -0,0 +1,32 @@
+/**
+ * Config service — manages resolved config lifecycle.
+ *
+ * The config is resolved during bootstrap (two-phase init per ADR-010)
+ * and registered via `registerConfigState`. This service reads from the
+ * global registry so trails can access it through `configService.from(ctx)`.
+ */
+import { InternalError, Result, service } from '@ontrails/core';
+import { z } from 'zod';
+
+import type { ConfigState } from './registry.js';
+import { getConfigState } from './registry.js';
+
+export const configService = service<ConfigState>('config', {
+  create: () => {
+    const state = getConfigState();
+    if (state === undefined) {
+      return Result.err(
+        new InternalError(
+          'Config state not registered — call registerConfigState at bootstrap'
+        )
+      );
+    }
+    return Result.ok(state);
+  },
+  description: 'Resolved application configuration',
+  metadata: { category: 'infrastructure' },
+  mock: (): ConfigState => ({
+    resolved: {},
+    schema: z.object({}),
+  }),
+});

package/src/define-config.ts

@@ -0,0 +1,134 @@
+/**
+ * Trails-specific config wrapper — `appConfig('trails', ...)` with
+ * framework conventions for loadout selection and local overrides.
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type { z } from 'zod';
+
+import { appConfig } from './app-config.js';
+import { resolveConfig } from './resolve.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Options for defining a Trails app config. */
+export interface DefineConfigOptions<T extends z.ZodType> {
+  readonly schema: T;
+  readonly base?: Partial<z.infer<T>>;
+  readonly loadouts?: Record<string, Partial<z.infer<T>>>;
+  /** When true, fall back to `NODE_ENV` when `TRAILS_ENV` is unset. */
+  readonly envFromNodeEnv?: boolean;
+}
+
+/** Options passed to `resolve()` on a defined config. */
+interface DefineConfigResolveOptions {
+  readonly loadout?: string;
+  readonly env?: Record<string, string | undefined>;
+  /** Working directory for local overrides discovery. Defaults to `process.cwd()`. */
+  readonly cwd?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Local overrides discovery
+// ---------------------------------------------------------------------------
+
+const LOCAL_OVERRIDE_CANDIDATES = ['local.ts', 'local.js'] as const;
+
+/**
+ * Discover and synchronously import a `.trails/config/local.{ts,js}` file.
+ *
+ * Skipped when `TRAILS_ENV=test` for hermetic test environments.
+ */
+const discoverLocalOverrides = async (
+  cwd: string,
+  envRecord: Record<string, string | undefined>
+): Promise<Record<string, unknown> | undefined> => {
+  if (envRecord['TRAILS_ENV'] === 'test') {
+    return undefined;
+  }
+
+  for (const filename of LOCAL_OVERRIDE_CANDIDATES) {
+    const candidate = join(cwd, '.trails', 'config', filename);
+    if (existsSync(candidate)) {
+      const mod: Record<string, unknown> = await import(candidate);
+      return (mod['default'] ?? mod) as Record<string, unknown>;
+    }
+  }
+
+  return undefined;
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Define Trails app config.
+ *
+ * This is `appConfig('trails', ...)` with the framework's own conventions:
+ * `TRAILS_ENV` selects the loadout. When `envFromNodeEnv` is true,
+ * `NODE_ENV` is used as a fallback when `TRAILS_ENV` is unset.
+ *
+ * @example
+ * ```ts
+ * const config = defineConfig({
+ *   schema: z.object({
+ *     port: z.number().default(3000),
+ *     debug: z.boolean().default(false),
+ *   }),
+ *   base: { port: 8080 },
+ *   loadouts: {
+ *     production: { debug: false },
+ *     test: { debug: true, port: 0 },
+ *   },
+ * });
+ *
+ * const result = config.resolve();
+ * ```
+ */
+export const defineConfig = <T extends z.ZodType>(
+  options: DefineConfigOptions<T>
+) => {
+  const config = appConfig('trails', {
+    formats: ['toml', 'json'],
+    schema: options.schema,
+  });
+
+  return {
+    ...config,
+    base: options.base,
+    loadouts: options.loadouts,
+    resolve: async (resolveOpts?: DefineConfigResolveOptions) => {
+      const envRecord = {
+        ...(resolveOpts?.env ?? process.env),
+      } as Record<string, string | undefined>;
+
+      if (
+        options.envFromNodeEnv &&
+        envRecord['TRAILS_ENV'] === undefined &&
+        envRecord['NODE_ENV'] !== undefined
+      ) {
+        envRecord['TRAILS_ENV'] = envRecord['NODE_ENV'];
+      }
+
+      const cwd = resolveOpts?.cwd ?? process.cwd();
+      const localOverrides = await discoverLocalOverrides(cwd, envRecord);
+
+      return resolveConfig({
+        base: options.base as Record<string, unknown> | undefined,
+        env: envRecord,
+        loadout: resolveOpts?.loadout ?? envRecord['TRAILS_ENV'],
+        loadouts: options.loadouts as
+          | Record<string, Record<string, unknown>>
+          | undefined,
+        localOverrides,
+        schema: options.schema,
+      });
+    },
+    schema: options.schema,
+  };
+};