@ontrails/config 1.0.0-beta.12

package/dist/trails/config-explain.js

@@ -0,0 +1,74 @@
+/**
+ * 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 { explainConfig } from '../explain.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, prefix) => prefix
+    ? entries.filter((entry) => entry.path === prefix || entry.path.startsWith(`${prefix}.`))
+    : entries;
+/** Build ExplainConfigOptions from ConfigState, omitting undefined layers. */
+const toExplainOptions = (state) => {
+    const base = {
+        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, options) => {
+    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],
+});
+//# sourceMappingURL=config-explain.js.map

package/dist/trails/config-explain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-explain.js","sourceRoot":"","sources":["../../src/trails/config-explain.ts"],"names":[],"mappings":"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"}

package/dist/trails/config-init.d.ts

@@ -0,0 +1,9 @@
+export declare const configInit: import("@ontrails/core").Trail<{
+    format: "toml" | "json" | "jsonc" | "yaml";
+    dir?: string | undefined;
+}, {
+    content: string;
+    format: string;
+    writtenFiles?: string[] | undefined;
+}>;
+//# sourceMappingURL=config-init.d.ts.map

package/dist/trails/config-init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-init.d.ts","sourceRoot":"","sources":["../../src/trails/config-init.ts"],"names":[],"mappings":"AA+DA,eAAO,MAAM,UAAU;;;;;;;EAgCrB,CAAC"}

package/dist/trails/config-init.js

@@ -0,0 +1,78 @@
+/**
+ * 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 { 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) => {
+    const artifacts = [];
+    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, schema) => {
+    await mkdir(dir, { recursive: true });
+    const artifacts = collectArtifacts(schema);
+    const written = [];
+    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;
+        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],
+});
+//# sourceMappingURL=config-init.js.map

package/dist/trails/config-init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-init.js","sourceRoot":"","sources":["../../src/trails/config-init.ts"],"names":[],"mappings":"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"}

package/dist/workspace.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Ensure the `.trails/` workspace directory exists with proper structure.
+ *
+ * Creates `config/`, `dev/`, and `generated/` subdirectories plus a
+ * `.gitignore` that excludes local-only files. Safe to call repeatedly —
+ * existing files are never overwritten.
+ */
+export declare const ensureWorkspace: (root: string) => Promise<void>;
+//# sourceMappingURL=workspace.d.ts.map

package/dist/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAmCA;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAU,MAAM,MAAM,KAAG,OAAO,CAAC,IAAI,CAQhE,CAAC"}

package/dist/workspace.js

@@ -0,0 +1,44 @@
+/**
+ * Ensure the `.trails/` workspace directory exists with proper structure.
+ *
+ * Auto-creates on first framework operation. The workspace holds local
+ * config overrides, development state, and generated artifacts that
+ * should not be committed to source control.
+ */
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+const WORKSPACE_DIRS = ['config', 'dev', 'generated'];
+const GITIGNORE_CONTENT = [
+    '# Local config overrides',
+    'config/',
+    '',
+    '# Development state',
+    'dev/',
+    '',
+    '# Generated artifacts',
+    'generated/',
+    '',
+].join('\n');
+/**
+ * Write `.gitignore` inside the workspace directory if it does not already exist.
+ */
+const writeGitignoreIfMissing = async (trailsDir) => {
+    const gitignorePath = join(trailsDir, '.gitignore');
+    const file = Bun.file(gitignorePath);
+    if (!(await file.exists())) {
+        await Bun.write(gitignorePath, GITIGNORE_CONTENT);
+    }
+};
+/**
+ * Ensure the `.trails/` workspace directory exists with proper structure.
+ *
+ * Creates `config/`, `dev/`, and `generated/` subdirectories plus a
+ * `.gitignore` that excludes local-only files. Safe to call repeatedly —
+ * existing files are never overwritten.
+ */
+export const ensureWorkspace = async (root) => {
+    const trailsDir = join(root, '.trails');
+    await Promise.all(WORKSPACE_DIRS.map((d) => mkdir(join(trailsDir, d), { recursive: true })));
+    await writeGitignoreIfMissing(trailsDir);
+};
+//# sourceMappingURL=workspace.js.map

package/dist/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,KAAK,EAAE,WAAW,CAAU,CAAC;AAE/D,MAAM,iBAAiB,GAAG;IACxB,0BAA0B;IAC1B,SAAS;IACT,EAAE;IACF,qBAAqB;IACrB,MAAM;IACN,EAAE;IACF,uBAAuB;IACvB,YAAY;IACZ,EAAE;CACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb;;GAEG;AACH,MAAM,uBAAuB,GAAG,KAAK,EAAE,SAAiB,EAAiB,EAAE;IACzE,MAAM,aAAa,GAAG,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IACpD,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IACrC,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC;QAC3B,MAAM,GAAG,CAAC,KAAK,CAAC,aAAa,EAAE,iBAAiB,CAAC,CAAC;IACpD,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,EAAE,IAAY,EAAiB,EAAE;IACnE,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAExC,MAAM,OAAO,CAAC,GAAG,CACf,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAC1E,CAAC;IAEF,MAAM,uBAAuB,CAAC,SAAS,CAAC,CAAC;AAC3C,CAAC,CAAC"}

package/dist/zod-utils.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared Zod introspection helpers used by config resolution, doctor,
+ * describe, explain, and collect modules.
+ */
+import type { z } from 'zod';
+/** Extract the Zod def record from any ZodType. */
+export declare const zodDef: (schema: z.ZodType) => Record<string, unknown>;
+/** Unwrap through optional/default/nullable wrappers to find the base schema. */
+export declare const unwrapToBase: (schema: z.ZodType) => z.ZodType;
+/** Check if a schema is (or wraps) a ZodObject by inspecting its def. */
+export declare const isZodObject: (schema: z.ZodType) => schema is z.ZodObject<Record<string, z.ZodType>>;
+/** Read a value at a dot-separated path from a plain object. */
+export declare const getAtPath: (obj: Record<string, unknown>, path: string) => unknown;
+//# sourceMappingURL=zod-utils.d.ts.map

package/dist/zod-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-utils.d.ts","sourceRoot":"","sources":["../src/zod-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,mDAAmD;AACnD,eAAO,MAAM,MAAM,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CACf,CAAC;AAKnD,iFAAiF;AACjF,eAAO,MAAM,YAAY,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,CAAC,CAAC,OAclD,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,WAAW,GACtB,QAAQ,CAAC,CAAC,OAAO,KAChB,MAAM,IAAI,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAGjD,CAAC;AAEF,gEAAgE;AAChE,eAAO,MAAM,SAAS,GACpB,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,MAAM,MAAM,KACX,OASF,CAAC"}

package/dist/zod-utils.js

@@ -0,0 +1,41 @@
+/**
+ * Shared Zod introspection helpers used by config resolution, doctor,
+ * describe, explain, and collect modules.
+ */
+/** Extract the Zod def record from any ZodType. */
+export const zodDef = (schema) => schema.def;
+/** Wrapper types that should be peeled before checking the base type. */
+const WRAPPER_TYPES = new Set(['optional', 'default', 'nullable']);
+/** Unwrap through optional/default/nullable wrappers to find the base schema. */
+export const unwrapToBase = (schema) => {
+    let current = schema;
+    for (let depth = 0; depth < 10; depth += 1) {
+        const def = zodDef(current);
+        if (!WRAPPER_TYPES.has(def['type'])) {
+            return current;
+        }
+        const inner = def['innerType'];
+        if (!inner) {
+            return current;
+        }
+        current = inner;
+    }
+    return current;
+};
+/** Check if a schema is (or wraps) a ZodObject by inspecting its def. */
+export const isZodObject = (schema) => {
+    const def = zodDef(unwrapToBase(schema));
+    return def['type'] === 'object' && 'shape' in def;
+};
+/** Read a value at a dot-separated path from a plain object. */
+export const getAtPath = (obj, path) => {
+    let current = obj;
+    for (const part of path.split('.')) {
+        if (typeof current !== 'object' || current === null) {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return current;
+};
+//# sourceMappingURL=zod-utils.js.map

package/dist/zod-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-utils.js","sourceRoot":"","sources":["../src/zod-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,mDAAmD;AACnD,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,MAAiB,EAA2B,EAAE,CACnE,MAAM,CAAC,GAAyC,CAAC;AAEnD,yEAAyE;AACzE,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,UAAU,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC;AAEnE,iFAAiF;AACjF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,MAAiB,EAAa,EAAE;IAC3D,IAAI,OAAO,GAAG,MAAM,CAAC;IACrB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,EAAE,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QAC3C,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;QAC5B,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAW,CAAC,EAAE,CAAC;YAC9C,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,MAAM,KAAK,GAAG,GAAG,CAAC,WAAW,CAA0B,CAAC;QACxD,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,OAAO,GAAG,KAAK,CAAC;IAClB,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC,CAAC;AAEF,yEAAyE;AACzE,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,MAAiB,EACiC,EAAE;IACpD,MAAM,GAAG,GAAG,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;IACzC,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,QAAQ,IAAI,OAAO,IAAI,GAAG,CAAC;AACpD,CAAC,CAAC;AAEF,gEAAgE;AAChE,MAAM,CAAC,MAAM,SAAS,GAAG,CACvB,GAA4B,EAC5B,IAAY,EACH,EAAE;IACX,IAAI,OAAO,GAAY,GAAG,CAAC;IAC3B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACpD,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,GAAI,OAAmC,CAAC,IAAI,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@ontrails/config",
+  "version": "1.0.0-beta.12",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint ./src",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "peerDependencies": {
+    "@ontrails/core": "^1.0.0-beta.12",
+    "zod": "^4.3.5"
+  }
+}

package/src/__tests__/app-config.test.ts

@@ -0,0 +1,329 @@
+import { describe, expect, test, beforeEach, afterEach } from 'bun:test';
+import { mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { z } from 'zod';
+
+import type { AppConfig } from '../app-config.js';
+import { appConfig } from '../app-config.js';
+import { describeConfig } from '../describe.js';
+import { checkConfig } from '../doctor.js';
+import { configRef } from '../ref.js';
+
+const testSchema = z.object({
+  output: z.string().describe('Output directory').default('./output'),
+  verbose: z.boolean().default(false),
+});
+
+const createJsonConfig = () =>
+  appConfig('myapp', {
+    formats: ['json'],
+    schema: testSchema,
+  });
+
+const writeJsonConfig = (filePath: string, output: string) =>
+  Bun.write(filePath, JSON.stringify({ output }));
+
+const resolveOutput = async (
+  config: AppConfig<typeof testSchema>,
+  filePath: string
+): Promise<string> => {
+  const result = await config.resolve({ path: filePath });
+  expect(result.isOk()).toBe(true);
+  return result.unwrap().output;
+};
+
+describe('appConfig()', () => {
+  describe('creation', () => {
+    test('returns an object with the provided name', () => {
+      const config = appConfig('myapp', { schema: testSchema });
+      expect(config.name).toBe('myapp');
+    });
+
+    test('returns the provided schema', () => {
+      const config = appConfig('myapp', { schema: testSchema });
+      expect(config.schema).toBe(testSchema);
+    });
+
+    test('defaults formats to toml, json, yaml when not specified', () => {
+      const config = appConfig('myapp', { schema: testSchema });
+      expect(config.formats).toEqual(['toml', 'json', 'yaml']);
+    });
+
+    test('uses provided formats', () => {
+      const config = appConfig('myapp', {
+        formats: ['json', 'jsonc'],
+        schema: testSchema,
+      });
+      expect(config.formats).toEqual(['json', 'jsonc']);
+    });
+
+    test('defaults dotfile to false when not specified', () => {
+      const config = appConfig('myapp', { schema: testSchema });
+      expect(config.dotfile).toBe(false);
+    });
+
+    test('uses provided dotfile value', () => {
+      const config = appConfig('myapp', {
+        dotfile: true,
+        schema: testSchema,
+      });
+      expect(config.dotfile).toBe(true);
+    });
+  });
+
+  describe('resolve() with explicit path', () => {
+    let tempDir: string;
+
+    beforeEach(async () => {
+      tempDir = await mkdtemp(join(tmpdir(), 'trails-config-'));
+    });
+
+    afterEach(async () => {
+      await rm(tempDir, { force: true, recursive: true });
+    });
+
+    test('reads and validates a JSON config file', async () => {
+      const filePath = join(tempDir, 'myapp.config.json');
+      await Bun.write(
+        filePath,
+        JSON.stringify({ output: './dist', verbose: true })
+      );
+
+      const config = createJsonConfig();
+      const result = await config.resolve({ path: filePath });
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap()).toEqual({ output: './dist', verbose: true });
+    });
+
+    test('reads and validates a TOML config file', async () => {
+      const filePath = join(tempDir, 'myapp.config.toml');
+      await Bun.write(filePath, 'output = "./build"\nverbose = true\n');
+
+      const config = appConfig('myapp', {
+        formats: ['toml'],
+        schema: testSchema,
+      });
+      const result = await config.resolve({ path: filePath });
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap()).toEqual({ output: './build', verbose: true });
+    });
+
+    test('applies schema defaults for missing fields', async () => {
+      const filePath = join(tempDir, 'myapp.config.json');
+      await Bun.write(filePath, JSON.stringify({}));
+
+      const config = createJsonConfig();
+      const result = await config.resolve({ path: filePath });
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap()).toEqual({ output: './output', verbose: false });
+    });
+
+    test('re-reads config files after they change on disk', async () => {
+      const filePath = join(tempDir, 'myapp.config.json');
+      await writeJsonConfig(filePath, './first');
+
+      const config = createJsonConfig();
+
+      expect(await resolveOutput(config, filePath)).toBe('./first');
+
+      await Bun.sleep(10);
+      await writeJsonConfig(filePath, './second');
+
+      expect(await resolveOutput(config, filePath)).toBe('./second');
+    });
+
+    test('returns Result.err when file does not exist', async () => {
+      const filePath = join(tempDir, 'nonexistent.json');
+
+      const config = createJsonConfig();
+      const result = await config.resolve({ path: filePath });
+
+      expect(result.isErr()).toBe(true);
+    });
+
+    test('returns Result.err when file has invalid content', async () => {
+      const filePath = join(tempDir, 'myapp.config.json');
+      await Bun.write(
+        filePath,
+        JSON.stringify({ output: 42, verbose: 'not-a-bool' })
+      );
+
+      const config = createJsonConfig();
+      const result = await config.resolve({ path: filePath });
+
+      expect(result.isErr()).toBe(true);
+    });
+  });
+
+  describe('resolve() with discovery', () => {
+    let tempDir: string;
+
+    beforeEach(async () => {
+      tempDir = await mkdtemp(join(tmpdir(), 'trails-config-'));
+    });
+
+    afterEach(async () => {
+      await rm(tempDir, { force: true, recursive: true });
+    });
+
+    test('discovers config file in cwd', async () => {
+      const filePath = join(tempDir, 'myapp.config.json');
+      await writeJsonConfig(filePath, './found');
+
+      const config = createJsonConfig();
+      const result = await config.resolve({ cwd: tempDir });
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap().output).toBe('./found');
+    });
+
+    test('discovers config file by walking up directories', async () => {
+      const nested = join(tempDir, 'a', 'b', 'c');
+      await mkdir(nested, { recursive: true });
+
+      const filePath = join(tempDir, 'myapp.config.json');
+      await Bun.write(filePath, JSON.stringify({ output: './parent' }));
+
+      const config = appConfig('myapp', {
+        formats: ['json'],
+        schema: testSchema,
+      });
+      const result = await config.resolve({ cwd: nested });
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap().output).toBe('./parent');
+    });
+
+    test('tries formats in order', async () => {
+      await Bun.write(
+        join(tempDir, 'myapp.config.toml'),
+        'output = "./from-toml"\n'
+      );
+      await Bun.write(
+        join(tempDir, 'myapp.config.json'),
+        JSON.stringify({ output: './from-json' })
+      );
+
+      const config = appConfig('myapp', {
+        formats: ['toml', 'json'],
+        schema: testSchema,
+      });
+      const result = await config.resolve({ cwd: tempDir });
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap().output).toBe('./from-toml');
+    });
+
+    test('returns Result.err when no config file found', async () => {
+      const config = appConfig('myapp', { schema: testSchema });
+      const result = await config.resolve({ cwd: tempDir });
+
+      expect(result.isErr()).toBe(true);
+    });
+  });
+
+  describe('file naming conventions', () => {
+    let tempDir: string;
+
+    beforeEach(async () => {
+      tempDir = await mkdtemp(join(tmpdir(), 'trails-config-'));
+    });
+
+    afterEach(async () => {
+      await rm(tempDir, { force: true, recursive: true });
+    });
+
+    test('dotfile: true searches for .myapprc.* files', async () => {
+      await Bun.write(
+        join(tempDir, '.myapprc.json'),
+        JSON.stringify({ output: './dotfile' })
+      );
+
+      const config = appConfig('myapp', {
+        dotfile: true,
+        formats: ['json'],
+        schema: testSchema,
+      });
+      const result = await config.resolve({ cwd: tempDir });
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap().output).toBe('./dotfile');
+    });
+
+    test('dotfile: false searches for myapp.config.* files', async () => {
+      await Bun.write(
+        join(tempDir, 'myapp.config.json'),
+        JSON.stringify({ output: './standard' })
+      );
+
+      const config = appConfig('myapp', {
+        dotfile: false,
+        formats: ['json'],
+        schema: testSchema,
+      });
+      const result = await config.resolve({ cwd: tempDir });
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap().output).toBe('./standard');
+    });
+
+    test('dotfile: true does NOT find myapp.config.* files', async () => {
+      await Bun.write(
+        join(tempDir, 'myapp.config.json'),
+        JSON.stringify({ output: './nope' })
+      );
+
+      const config = appConfig('myapp', {
+        dotfile: true,
+        formats: ['json'],
+        schema: testSchema,
+      });
+      const result = await config.resolve({ cwd: tempDir });
+
+      expect(result.isErr()).toBe(true);
+    });
+  });
+
+  describe('method delegations', () => {
+    test('describe() returns same result as describeConfig(schema)', () => {
+      const config = appConfig('myapp', { schema: testSchema });
+      const methodResult = config.describe();
+      const standaloneResult = describeConfig(testSchema);
+
+      expect(methodResult).toEqual(standaloneResult);
+    });
+
+    test('check() returns same result as checkConfig(schema, values)', () => {
+      const config = appConfig('myapp', { schema: testSchema });
+      const values = { output: './dist', verbose: true };
+
+      const methodResult = config.check(values);
+      const standaloneResult = checkConfig(testSchema, values);
+
+      expect(methodResult).toEqual(standaloneResult);
+    });
+
+    test('ref() returns same result as configRef(path)', () => {
+      const config = appConfig('myapp', { schema: testSchema });
+      const methodResult = config.ref('output');
+      const standaloneResult = configRef('output');
+
+      expect(methodResult).toEqual(standaloneResult);
+    });
+
+    test('explain() delegates to explainConfig with bound schema', () => {
+      const config = appConfig('myapp', { schema: testSchema });
+      const resolved = { output: './dist', verbose: true };
+
+      const result = config.explain({ resolved });
+
+      expect(result.length).toBeGreaterThan(0);
+      expect(result[0]?.path).toBeDefined();
+      expect(result[0]?.source).toBeDefined();
+    });
+  });
+});