@ontrails/config 0.2.0

package/src/resolve.ts

@@ -0,0 +1,196 @@
+/**
+ * Config resolution engine — merges config from multiple sources through
+ * a deterministic stack: defaults → base → profile → local → env.
+ */
+
+import type { z } from 'zod';
+
+import { Result, ValidationError } from '@ontrails/core';
+
+import { collectConfigMeta } from './collect.js';
+import { deepMerge } from './merge.js';
+import {
+  coerceEnvValue,
+  getSchemaAtPath,
+  isZodContainer,
+  zodDef,
+} from './zod-utils.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Options for resolving config through the full stack. */
+export interface DeriveConfigOptions<T extends z.ZodType> {
+  readonly schema: T;
+  readonly base?: Record<string, unknown> | undefined;
+  readonly profiles?: Record<string, Record<string, unknown>> | undefined;
+  readonly profile?: string | undefined;
+  readonly localOverrides?: Record<string, unknown> | undefined;
+  readonly env?: Record<string, string | undefined> | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// 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;
+};
+
+// ---------------------------------------------------------------------------
+// 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 = getSchemaAtPath(schema, path);
+  if (fieldSchema && isZodContainer(fieldSchema)) {
+    return;
+  }
+  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 → profile → local overrides. */
+const mergeLayers = (
+  base: Record<string, unknown> | undefined,
+  profiles: Record<string, Record<string, unknown>> | undefined,
+  profile: string | undefined,
+  localOverrides: Record<string, unknown> | undefined
+): Record<string, unknown> => {
+  let merged: Record<string, unknown> = {};
+  if (base) {
+    merged = deepMerge(merged, base);
+  }
+
+  const selected = profile && profiles ? profiles[profile] : 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
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive config through the full stack: defaults → base → profile → local → env.
+ * Returns `Result.ok` with the validated config, or `Result.err` on validation failure.
+ */
+export const deriveConfig = <T extends z.ZodType>(
+  options: DeriveConfigOptions<T>
+): Result<z.infer<T>, Error> => {
+  let merged = mergeLayers(
+    options.base,
+    options.profiles,
+    options.profile,
+    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 ValidationError(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,95 @@
+/**
+ * Infrastructure trail that validates config values against a schema.
+ *
+ * Returns structured field reports indicating which fields are valid,
+ * missing, invalid, deprecated, or using defaults.
+ */
+import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { configResource } from '../config-resource.js';
+import { collectConfigMeta } from '../collect.js';
+import { checkConfig } from '../doctor.js';
+import { deepMerge } from '../merge.js';
+import { isLikelySecret } from '../secret-heuristics.js';
+
+const fieldReportSchema = z.object({
+  message: z.string(),
+  path: z.string(),
+  redacted: z.boolean().optional(),
+  status: z.enum(['valid', 'missing', 'invalid', 'deprecated', 'default']),
+  value: z.unknown().optional(),
+});
+
+const outputSchema = z.object({
+  fields: z.array(fieldReportSchema),
+  valid: z.boolean(),
+});
+
+type ConfigCheckFieldReport = ReturnType<typeof checkConfig>['fields'][number] &
+  Readonly<{
+    redacted?: 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;
+};
+
+const redactSecretFields = (
+  schema: z.ZodObject<Record<string, z.ZodType>>,
+  fields: ReturnType<typeof checkConfig>['fields']
+): ConfigCheckFieldReport[] => {
+  const meta = collectConfigMeta(schema);
+  const redactedPaths = new Set(
+    [...meta.entries()]
+      .filter(
+        ([, fieldMeta]) =>
+          fieldMeta.secret === true ||
+          (fieldMeta.env !== undefined && isLikelySecret(fieldMeta.env))
+      )
+      .map(([path]) => path)
+  );
+  return fields.map((field) => {
+    const shouldRedact = [...redactedPaths].some(
+      (path) => field.path === path || field.path.startsWith(`${path}.`)
+    );
+    if (!shouldRedact || !('value' in field) || field.value === undefined) {
+      return field;
+    }
+
+    return { ...field, redacted: true, value: '[REDACTED]' };
+  });
+};
+
+export const configCheck = trail('config.check', {
+  examples: [
+    {
+      input: {},
+      name: 'Check current config',
+    },
+  ],
+  implementation: (input, ctx) => {
+    const state = configResource.from(ctx);
+    const effective = mergeValues(state.resolved, input.values);
+    const checked = checkConfig(state.schema, effective);
+    return Result.ok({
+      fields: redactSecretFields(state.schema, checked.fields),
+      valid: checked.valid,
+    });
+  },
+  input: z.object({
+    values: z
+      .record(z.string(), z.unknown())
+      .describe('Config values to check (merged with resolved)')
+      .default({}),
+  }),
+  intent: 'read',
+  meta: { category: 'infrastructure' },
+  output: outputSchema,
+  resources: [configResource],
+});

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 { configResource } from '../config-resource.js';
+import { deriveConfigFields } from '../derive-fields.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',
+    },
+  ],
+  implementation: (_input, ctx) => {
+    const state = configResource.from(ctx);
+    const fields = deriveConfigFields(state.schema);
+    return Result.ok({ fields: [...fields] });
+  },
+  input: z.object({}),
+  intent: 'read',
+  meta: { category: 'infrastructure' },
+  output: outputSchema,
+  resources: [configResource],
+});

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 { configResource } from '../config-resource.js';
+import {
+  deriveConfigEnvExample,
+  deriveConfigExample,
+  deriveConfigJsonSchema,
+} from '../derive/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 = deriveConfigEnvExample(schema);
+  if (envContent.length > 0) {
+    artifacts.push(['.env.example', envContent]);
+  }
+  artifacts.push([
+    '.schema.json',
+    JSON.stringify(deriveConfigJsonSchema(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',
+    },
+  ],
+  implementation: async (input, ctx) => {
+    const state = configResource.from(ctx);
+    const schema = state.schema as z.ZodObject<Record<string, z.ZodType>>;
+    const content = deriveConfigExample(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 });
+  },
+  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',
+  meta: { category: 'infrastructure' },
+  output: outputSchema,
+  resources: [configResource],
+});

package/src/trails-config-file.ts

@@ -0,0 +1,136 @@
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { NotFoundError, ValidationError } from '@ontrails/core';
+
+import {
+  findTrailsConfigPaths,
+  findTrailsLocalConfigPaths,
+} from './trails-conventions.js';
+
+export interface LoadedTrailsConfigValue {
+  readonly configPath?: string | undefined;
+  readonly value?: unknown;
+}
+
+const MODULE_EXTENSIONS = new Set(['.ts', '.mts', '.js', '.mjs']);
+const DATA_EXTENSIONS = new Set(['.json', '.jsonc', '.yaml', '.toml']);
+
+const extensionFor = (filePath: string): string | undefined => {
+  for (const extension of [...MODULE_EXTENSIONS, ...DATA_EXTENSIONS]) {
+    if (filePath.endsWith(extension)) {
+      return extension;
+    }
+  }
+  return undefined;
+};
+
+const isModuleExtension = (extension: string | undefined): boolean =>
+  extension !== undefined && MODULE_EXTENSIONS.has(extension);
+
+export const parseTrailsConfigData = (
+  filePath: string,
+  text: string
+): unknown => {
+  const extension = extensionFor(filePath);
+  try {
+    switch (extension) {
+      case '.json': {
+        return JSON.parse(text);
+      }
+      case '.jsonc': {
+        return Bun.JSONC.parse(text);
+      }
+      case '.toml': {
+        return Bun.TOML.parse(text);
+      }
+      case '.yaml': {
+        return Bun.YAML.parse(text);
+      }
+      default: {
+        throw new ValidationError(
+          `Unsupported Trails config file: ${filePath}`
+        );
+      }
+    }
+  } catch (error) {
+    if (error instanceof ValidationError) {
+      throw error;
+    }
+    throw new ValidationError(
+      `Failed to parse Trails config file: ${filePath}`,
+      {
+        cause: error instanceof Error ? error : new Error(String(error)),
+        context: { path: filePath },
+      }
+    );
+  }
+};
+
+export const loadTrailsConfigFileValue = async (
+  filePath: string
+): Promise<unknown> => {
+  const extension = extensionFor(filePath);
+  if (isModuleExtension(extension)) {
+    const url = pathToFileURL(filePath);
+    url.searchParams.set('t', Date.now().toString());
+    const mod = (await import(url.href)) as Record<string, unknown>;
+    return mod['default'] ?? mod;
+  }
+
+  const text = await Bun.file(filePath).text();
+  return parseTrailsConfigData(filePath, text);
+};
+
+const findSingleConfigPath = (
+  paths: readonly string[],
+  label: string
+): string | undefined => {
+  if (paths.length <= 1) {
+    return paths[0];
+  }
+  throw new ValidationError(
+    `Multiple ${label} config files found: ${paths.join(', ')}. Keep one config file per project root.`
+  );
+};
+
+export const loadTrailsConfigValue = async ({
+  configPath,
+  rootDir,
+}: {
+  readonly configPath?: string | undefined;
+  readonly rootDir: string;
+}): Promise<LoadedTrailsConfigValue> => {
+  const located =
+    configPath === undefined
+      ? findSingleConfigPath(findTrailsConfigPaths(rootDir), 'Trails')
+      : resolve(rootDir, configPath);
+
+  if (located === undefined) {
+    return {};
+  }
+  if (!existsSync(located)) {
+    throw new NotFoundError(`Trails config file not found: ${located}`, {
+      context: { path: located },
+    });
+  }
+
+  return {
+    configPath: located,
+    value: await loadTrailsConfigFileValue(located),
+  };
+};
+
+export const loadTrailsLocalConfigValue = async (
+  rootDir: string
+): Promise<LoadedTrailsConfigValue> => {
+  const located = findSingleConfigPath(
+    findTrailsLocalConfigPaths(rootDir),
+    'Trails local'
+  );
+
+  return located === undefined
+    ? {}
+    : { configPath: located, value: await loadTrailsConfigFileValue(located) };
+};