@ontrails/config 1.0.0-beta.12

package/src/merge.ts

@@ -0,0 +1,43 @@
+/**
+ * Simple recursive deep merge for config objects.
+ *
+ * - Objects merge recursively
+ * - Arrays replace (no concatenation)
+ * - Primitives replace
+ * - `undefined` values in source are skipped
+ */
+
+/** Check whether a value is a plain object (not array, null, or class instance). */
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' &&
+  value !== null &&
+  !Array.isArray(value) &&
+  Object.getPrototypeOf(value) === Object.prototype;
+
+/**
+ * Deep-merge `source` into `target`, returning a new object.
+ *
+ * Does not mutate either input. Undefined values in source are skipped,
+ * preserving the target's value at that key.
+ */
+export const deepMerge = (
+  target: Record<string, unknown>,
+  source: Record<string, unknown>
+): Record<string, unknown> => {
+  const result: Record<string, unknown> = { ...target };
+
+  for (const [key, sourceValue] of Object.entries(source)) {
+    if (sourceValue === undefined) {
+      continue;
+    }
+
+    const targetValue = result[key];
+
+    result[key] =
+      isPlainObject(targetValue) && isPlainObject(sourceValue)
+        ? deepMerge(targetValue, sourceValue)
+        : sourceValue;
+  }
+
+  return result;
+};

package/src/ref.ts

@@ -0,0 +1,38 @@
+/**
+ * Lazy config reference markers for trail input defaults.
+ *
+ * A `ConfigRef` is a marker object that can be embedded as a trail input
+ * default. When resolution is wired into the execution pipeline, it will
+ * be replaced with the live config value at the given path.
+ *
+ * Note: resolution is not yet wired into the execution pipeline.
+ * Currently this module provides the marker type and type guard only.
+ * Trail input defaults using `configRef()` will not be resolved
+ * automatically until the execution pipeline integration ships.
+ */
+
+/** Marker object representing a lazy reference to a config field. */
+export interface ConfigRef {
+  readonly __configRef: true;
+  readonly path: string;
+}
+
+/**
+ * Create a lazy reference to a config field for use as a trail input default.
+ *
+ * Note: resolution is not yet automatic. See module-level docs.
+ *
+ */
+export const configRef = (path: string): ConfigRef => ({
+  __configRef: true,
+  path,
+});
+
+/**
+ * Type guard: detect whether an unknown value is a `ConfigRef` marker.
+ */
+export const isConfigRef = (value?: unknown): value is ConfigRef =>
+  typeof value === 'object' &&
+  value !== null &&
+  '__configRef' in value &&
+  (value as Record<string, unknown>)['__configRef'] === true;

package/src/registry.ts

@@ -0,0 +1,33 @@
+/**
+ * Module-level config state registry.
+ *
+ * Config is resolved once at bootstrap (two-phase init per ADR-010) and
+ * registered here so `configService` can surface it to trails. This is
+ * a process-level singleton — config resolution is inherently global.
+ */
+import type { z } from 'zod';
+
+/** Resolved config state carrying the schema and all layer values. */
+export interface ConfigState {
+  readonly schema: z.ZodObject<Record<string, z.ZodType>>;
+  readonly resolved: Record<string, unknown>;
+  readonly base?: Record<string, unknown>;
+  readonly loadout?: Record<string, unknown>;
+  readonly local?: Record<string, unknown>;
+  readonly env?: Record<string, string | undefined>;
+}
+
+let current: ConfigState | undefined;
+
+/** Register resolved config state at bootstrap. */
+export const registerConfigState = (state: ConfigState): void => {
+  current = state;
+};
+
+/** Read the registered config state. Returns `undefined` before registration. */
+export const getConfigState = (): ConfigState | undefined => current;
+
+/** Clear registered state. Primarily useful in tests. */
+export const clearConfigState = (): void => {
+  current = undefined;
+};

package/src/resolve.ts

@@ -0,0 +1,279 @@
+/**
+ * Config resolution engine — merges config from multiple sources through
+ * a deterministic stack: defaults → base → loadout → local → env.
+ */
+
+import type { z } from 'zod';
+
+import { Result } from '@ontrails/core';
+
+import { collectConfigMeta } from './collect.js';
+import { deepMerge } from './merge.js';
+import { zodDef } from './zod-utils.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Options for resolving config through the full stack. */
+export interface ResolveConfigOptions<T extends z.ZodType> {
+  readonly schema: T;
+  readonly base?: Record<string, unknown> | undefined;
+  readonly loadouts?: Record<string, Record<string, unknown>> | undefined;
+  readonly loadout?: string | undefined;
+  readonly localOverrides?: Record<string, unknown> | undefined;
+  readonly env?: Record<string, string | undefined> | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Env coercion helpers (defined before consumers)
+// ---------------------------------------------------------------------------
+
+/** Boolean string values we accept from environment variables. */
+const BOOL_TRUE = new Set(['true', '1']);
+const BOOL_FALSE = new Set(['false', '0']);
+
+/** Primitive type names we can coerce env strings into. */
+const PRIMITIVE_TYPES = new Set(['number', 'boolean', 'string']);
+
+/** Try to advance one level through a Zod wrapper, returning the inner type or undefined. */
+const unwrapOne = (
+  schema: z.ZodType
+): { typeName: string | undefined; inner: z.ZodType | undefined } => {
+  const def = zodDef(schema);
+  return {
+    inner: def['innerType'] as z.ZodType | undefined,
+    typeName: def['type'] as string | undefined,
+  };
+};
+
+/** Unwrap ZodDefault / ZodOptional / ZodNullable to find the base type name. */
+const resolveBaseTypeName = (schema: z.ZodType): string => {
+  let current: z.ZodType = schema;
+
+  for (let depth = 0; depth < 10; depth += 1) {
+    const { typeName, inner } = unwrapOne(current);
+    if (typeName && PRIMITIVE_TYPES.has(typeName)) {
+      return typeName;
+    }
+    if (!inner) {
+      break;
+    }
+    current = inner;
+  }
+
+  return 'string';
+};
+
+/** Coerce a boolean env string. Returns the original string if unrecognized. */
+const coerceBooleanEnv = (raw: string): unknown => {
+  if (BOOL_TRUE.has(raw)) {
+    return true;
+  }
+  if (BOOL_FALSE.has(raw)) {
+    return false;
+  }
+  return raw;
+};
+
+/** Coerce env var lookup table keyed by base type name. */
+const ENV_COERCERS: Record<string, (raw: string) => unknown> = {
+  boolean: coerceBooleanEnv,
+  number: (raw: string) => {
+    const n = Number(raw);
+    return Number.isNaN(n) ? raw : n;
+  },
+};
+
+/** Coerce a string env value to the type expected by the schema field. */
+const coerceEnvValue = (raw: string, schema: z.ZodType): unknown => {
+  const coercer = ENV_COERCERS[resolveBaseTypeName(schema)];
+  return coercer ? coercer(raw) : raw;
+};
+
+// ---------------------------------------------------------------------------
+// Path utilities
+// ---------------------------------------------------------------------------
+
+/** Navigate one step of a nested object, creating an intermediate if needed. */
+const navigateOrCreate = (
+  current: Record<string, unknown>,
+  key: string
+): Record<string, unknown> => {
+  const next = current[key];
+  if (typeof next === 'object' && next !== null && !Array.isArray(next)) {
+    return next as Record<string, unknown>;
+  }
+  const nested: Record<string, unknown> = {};
+  current[key] = nested;
+  return nested;
+};
+
+/** Ensure a nested path exists in an object, creating intermediates as needed. */
+const ensurePath = (
+  obj: Record<string, unknown>,
+  parts: readonly string[]
+): Record<string, unknown> => {
+  let current = obj;
+  for (const part of parts) {
+    current = navigateOrCreate(current, part);
+  }
+  return current;
+};
+
+/** Set a value at a dot-separated path in a plain object. */
+const setAtPath = (
+  obj: Record<string, unknown>,
+  path: string,
+  value: unknown
+): void => {
+  const parts = path.split('.');
+  const parent = ensurePath(obj, parts.slice(0, -1));
+  parent[parts.at(-1) as string] = value;
+};
+
+/** Resolve one step of a Zod shape walk: find the field schema for a key. */
+const resolveShapeStep = (
+  current: z.ZodType,
+  key: string
+): z.ZodType | undefined => {
+  const shape = zodDef(current)['shape'] as
+    | Record<string, z.ZodType>
+    | undefined;
+  return shape?.[key];
+};
+
+/** Walk a Zod schema shape to find the field at a dot-separated path. */
+const getFieldSchema = (
+  schema: z.ZodType,
+  path: string
+): z.ZodType | undefined => {
+  let current: z.ZodType = schema;
+  for (const part of path.split('.')) {
+    const next = resolveShapeStep(current, part);
+    if (!next) {
+      return undefined;
+    }
+    current = next;
+  }
+  return current;
+};
+
+// ---------------------------------------------------------------------------
+// Env overlay
+// ---------------------------------------------------------------------------
+
+/** Coerce and set a single env override into the result object. */
+const applyOneEnvOverride = (
+  result: Record<string, unknown>,
+  schema: z.ZodType,
+  path: string,
+  envValue: string
+): void => {
+  const fieldSchema = getFieldSchema(schema, path);
+  const coerced = fieldSchema
+    ? coerceEnvValue(envValue, fieldSchema)
+    : envValue;
+  setAtPath(result, path, coerced);
+};
+
+/** Resolve a single env binding: look up the var, apply if present. */
+const resolveEnvBinding = (
+  result: Record<string, unknown>,
+  schema: z.ZodType,
+  path: string,
+  envVar: string,
+  envVars: Record<string, string | undefined>
+): void => {
+  const envValue = envVars[envVar];
+  if (envValue !== undefined) {
+    applyOneEnvOverride(result, schema, path, envValue);
+  }
+};
+
+/** Apply env var overrides based on schema metadata. */
+const applyEnvOverrides = (
+  merged: Record<string, unknown>,
+  schema: z.ZodType,
+  envVars: Record<string, string | undefined>
+): Record<string, unknown> => {
+  if (zodDef(schema)['type'] !== 'object') {
+    return merged;
+  }
+
+  const meta = collectConfigMeta(
+    schema as z.ZodObject<Record<string, z.ZodType>>
+  );
+  const result = deepMerge({}, merged);
+
+  for (const [path, fieldMeta] of meta) {
+    if (fieldMeta.env) {
+      resolveEnvBinding(result, schema, path, fieldMeta.env, envVars);
+    }
+  }
+
+  return result;
+};
+
+// ---------------------------------------------------------------------------
+// Merge pipeline
+// ---------------------------------------------------------------------------
+
+/** Apply the layered merge: base → loadout → local overrides. */
+const mergeLayers = (
+  base: Record<string, unknown> | undefined,
+  loadouts: Record<string, Record<string, unknown>> | undefined,
+  loadout: string | undefined,
+  localOverrides: Record<string, unknown> | undefined
+): Record<string, unknown> => {
+  let merged: Record<string, unknown> = {};
+  if (base) {
+    merged = deepMerge(merged, base);
+  }
+
+  const selected = loadout && loadouts ? loadouts[loadout] : undefined;
+  if (selected) {
+    merged = deepMerge(merged, selected);
+  }
+
+  if (localOverrides) {
+    merged = deepMerge(merged, localOverrides);
+  }
+  return merged;
+};
+
+/** Format Zod issues into a human-readable error message. */
+const formatValidationError = (
+  issues: readonly { path: PropertyKey[]; message: string }[]
+): string =>
+  `Config validation failed: ${issues.map((i) => `${String(i.path.join('.'))}: ${i.message}`).join(', ')}`;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve config through the full stack: defaults → base → loadout → local → env.
+ * Returns `Result.ok` with the validated config, or `Result.err` on validation failure.
+ */
+export const resolveConfig = <T extends z.ZodType>(
+  options: ResolveConfigOptions<T>
+): Result<z.infer<T>, Error> => {
+  let merged = mergeLayers(
+    options.base,
+    options.loadouts,
+    options.loadout,
+    options.localOverrides
+  );
+
+  if (options.env) {
+    merged = applyEnvOverrides(merged, options.schema, options.env);
+  }
+
+  const parsed = options.schema.safeParse(merged);
+  if (parsed.success) {
+    return Result.ok(parsed.data as z.infer<T>);
+  }
+
+  return Result.err(new Error(formatValidationError(parsed.error.issues)));
+};

package/src/secret-heuristics.ts

@@ -0,0 +1,13 @@
+/**
+ * Heuristic detection of secret env var names.
+ *
+ * Matches common suffixes like `_SECRET`, `_TOKEN`, `_KEY`, `_PASSWORD`,
+ * and `_CREDENTIALS` so that generated `.env.example` files and provenance
+ * output can redact likely-secret values even without explicit `secret()`.
+ */
+
+const SECRET_PATTERN = /_SECRET$|_TOKEN$|_KEY$|_PASSWORD$|_CREDENTIALS$/i;
+
+/** Return true when `envName` looks like it holds a secret value. */
+export const isLikelySecret = (envName: string): boolean =>
+  SECRET_PATTERN.test(envName);

package/src/trails/config-check.ts

@@ -0,0 +1,60 @@
+/**
+ * Infrastructure trail that validates config values against a schema.
+ *
+ * Returns structured diagnostics indicating which fields are valid,
+ * missing, invalid, deprecated, or using defaults.
+ */
+import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { configService } from '../config-service.js';
+import { checkConfig } from '../doctor.js';
+import { deepMerge } from '../merge.js';
+
+const diagnosticSchema = z.object({
+  message: z.string(),
+  path: z.string(),
+  status: z.enum(['valid', 'missing', 'invalid', 'deprecated', 'default']),
+});
+
+const outputSchema = z.object({
+  diagnostics: z.array(diagnosticSchema),
+  valid: z.boolean(),
+});
+
+/** Merge input values on top of resolved config values. */
+const mergeValues = (
+  resolved: Record<string, unknown>,
+  overrides: Record<string, unknown>
+): Record<string, unknown> => {
+  const hasOverrides = Object.keys(overrides).length > 0;
+  return hasOverrides ? deepMerge(resolved, overrides) : resolved;
+};
+
+export const configCheck = trail('config.check', {
+  examples: [
+    {
+      input: {},
+      name: 'Check current config',
+    },
+  ],
+  input: z.object({
+    values: z
+      .record(z.string(), z.unknown())
+      .describe('Config values to check (merged with resolved)')
+      .default({}),
+  }),
+  intent: 'read',
+  metadata: { category: 'infrastructure' },
+  output: outputSchema,
+  run: (input, ctx) => {
+    const state = configService.from(ctx);
+    const effective = mergeValues(state.resolved, input.values);
+    const checked = checkConfig(state.schema, effective);
+    return Result.ok({
+      diagnostics: [...checked.diagnostics],
+      valid: checked.valid,
+    });
+  },
+  services: [configService],
+});

package/src/trails/config-describe.ts

@@ -0,0 +1,44 @@
+/**
+ * Infrastructure trail that describes all config fields in a schema.
+ *
+ * Returns a structured catalog of field definitions suitable for
+ * CLI rendering or agent inspection.
+ */
+import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { configService } from '../config-service.js';
+import { describeConfig } from '../describe.js';
+
+const fieldSchema = z.object({
+  deprecated: z.string().optional(),
+  description: z.string().optional(),
+  env: z.string().optional(),
+  path: z.string(),
+  required: z.boolean(),
+  secret: z.boolean().optional(),
+  type: z.string(),
+});
+
+const outputSchema = z.object({
+  fields: z.array(fieldSchema),
+});
+
+export const configDescribe = trail('config.describe', {
+  examples: [
+    {
+      input: {},
+      name: 'Describe all config fields',
+    },
+  ],
+  input: z.object({}),
+  intent: 'read',
+  metadata: { category: 'infrastructure' },
+  output: outputSchema,
+  run: (_input, ctx) => {
+    const state = configService.from(ctx);
+    const fields = describeConfig(state.schema);
+    return Result.ok({ fields: [...fields] });
+  },
+  services: [configService],
+});

package/src/trails/config-explain.ts

@@ -0,0 +1,93 @@
+/**
+ * Infrastructure trail that exposes config provenance.
+ *
+ * Returns resolved config entries with source information so agents
+ * and operators can answer "where did this value come from?"
+ */
+import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { configService } from '../config-service.js';
+import type { ExplainConfigOptions } from '../explain.js';
+import { explainConfig } from '../explain.js';
+import type { ConfigState } from '../registry.js';
+
+const provenanceEntrySchema = z.object({
+  path: z.string(),
+  redacted: z.boolean(),
+  source: z.string(),
+  value: z.unknown(),
+});
+
+const outputSchema = z.object({
+  entries: z.array(provenanceEntrySchema),
+});
+
+/** Filter provenance entries by path prefix when specified. */
+const filterByPath = (
+  entries: readonly { readonly path: string }[],
+  prefix: string
+): readonly { readonly path: string }[] =>
+  prefix
+    ? entries.filter(
+        (entry) => entry.path === prefix || entry.path.startsWith(`${prefix}.`)
+      )
+    : entries;
+
+/** Build ExplainConfigOptions from ConfigState, omitting undefined layers. */
+const toExplainOptions = (
+  state: ConfigState
+): ExplainConfigOptions<typeof state.schema> => {
+  const base: ExplainConfigOptions<typeof state.schema> = {
+    resolved: state.resolved,
+    schema: state.schema,
+  };
+  if (state.base) {
+    return { ...base, base: state.base };
+  }
+  return base;
+};
+
+/** Enrich explain options with env and layer overrides from state. */
+const enrichOptions = (
+  state: ConfigState,
+  options: ExplainConfigOptions<typeof state.schema>
+): ExplainConfigOptions<typeof state.schema> => {
+  let enriched = options;
+  if (state.env) {
+    enriched = { ...enriched, env: state.env };
+  }
+  if (state.loadout) {
+    enriched = { ...enriched, loadout: state.loadout };
+  }
+  if (state.local) {
+    enriched = { ...enriched, local: state.local };
+  }
+  return enriched;
+};
+
+export const configExplain = trail('config.explain', {
+  examples: [
+    {
+      input: {},
+      name: 'Explain all fields',
+    },
+  ],
+  input: z.object({
+    path: z
+      .string()
+      .describe('Config field path to explain (or empty for all)')
+      .default(''),
+  }),
+  intent: 'read',
+  metadata: { category: 'infrastructure' },
+  output: outputSchema,
+  run: (input, ctx) => {
+    const state = configService.from(ctx);
+    const options = enrichOptions(state, toExplainOptions(state));
+    const entries = explainConfig(options);
+    const filtered = filterByPath(entries, input.path);
+    return Result.ok({ entries: [...filtered] });
+  },
+  services: [configService],
+});

package/src/trails/config-init.ts

@@ -0,0 +1,96 @@
+/**
+ * Infrastructure trail that generates an example config file.
+ *
+ * Produces TOML, JSON, JSONC, or YAML output from the registered
+ * config schema, with defaults shown and deprecated fields annotated.
+ *
+ * When `dir` is provided, also writes `.env.example` and `.schema.json`
+ * to the specified directory.
+ */
+import { join } from 'node:path';
+import { mkdir } from 'node:fs/promises';
+
+import { Result, trail } from '@ontrails/core';
+import type { z } from 'zod';
+import { z as zod } from 'zod';
+
+import { configService } from '../config-service.js';
+import {
+  generateEnvExample,
+  generateExample,
+  generateJsonSchema,
+} from '../generate/index.js';
+
+const formatEnum = zod.enum(['toml', 'json', 'jsonc', 'yaml']);
+
+const outputSchema = zod.object({
+  content: zod.string(),
+  format: zod.string(),
+  writtenFiles: zod.array(zod.string()).optional(),
+});
+
+/** Collect artifacts to write: [relativeName, content] pairs. */
+const collectArtifacts = (
+  schema: z.ZodObject<Record<string, z.ZodType>>
+): [string, string][] => {
+  const artifacts: [string, string][] = [];
+  const envContent = generateEnvExample(schema);
+  if (envContent.length > 0) {
+    artifacts.push(['.env.example', envContent]);
+  }
+  artifacts.push([
+    '.schema.json',
+    JSON.stringify(generateJsonSchema(schema), null, 2),
+  ]);
+  return artifacts;
+};
+
+/** Write generated artifacts to the target directory. */
+const writeArtifacts = async (
+  dir: string,
+  schema: z.ZodObject<Record<string, z.ZodType>>
+): Promise<string[]> => {
+  await mkdir(dir, { recursive: true });
+  const artifacts = collectArtifacts(schema);
+  const written: string[] = [];
+  for (const [name, content] of artifacts) {
+    const fullPath = join(dir, name);
+    await Bun.write(fullPath, content);
+    written.push(fullPath);
+  }
+  return written;
+};
+
+export const configInit = trail('config.init', {
+  examples: [
+    {
+      input: {},
+      name: 'Generate TOML example',
+    },
+  ],
+  input: zod.object({
+    dir: zod
+      .string()
+      .describe('Directory to write generated artifacts to')
+      .optional(),
+    format: formatEnum
+      .describe('Output format for the example config file')
+      .default('toml'),
+  }),
+  intent: 'write',
+  metadata: { category: 'infrastructure' },
+  output: outputSchema,
+  run: async (input, ctx) => {
+    const state = configService.from(ctx);
+    const schema = state.schema as z.ZodObject<Record<string, z.ZodType>>;
+    const content = generateExample(schema, input.format);
+
+    if (input.dir) {
+      const writtenFiles = await writeArtifacts(input.dir, schema);
+      return Result.ok({ content, format: input.format, writtenFiles });
+    }
+
+    return Result.ok({ content, format: input.format });
+  },
+  services: [configService],
+});