@ontrails/config 1.0.0-beta.12

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

@@ -0,0 +1,210 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createServiceLookup } from '@ontrails/core';
+import type { TrailContext } from '@ontrails/core';
+import { z } from 'zod';
+
+import { env } from '../extensions.js';
+import type { ConfigState } from '../registry.js';
+import { configInit } from '../trails/config-init.js';
+
+/**
+ * Build a TrailContext with configService resolved in extensions.
+ */
+const buildCtx = (state: ConfigState): TrailContext => {
+  const extensions = { config: state };
+  const ctx: TrailContext = {
+    cwd: '/tmp',
+    env: {},
+    extensions,
+    requestId: 'test',
+    service: undefined as unknown as TrailContext['service'],
+    signal: AbortSignal.timeout(5000),
+    workspaceRoot: '/tmp',
+  };
+  const withLookup = {
+    ...ctx,
+    service: createServiceLookup(() => withLookup),
+  };
+  return withLookup;
+};
+
+const testSchema = z.object({
+  host: z.string().default('localhost'),
+  port: z.number().default(3000),
+});
+
+const testState: ConfigState = {
+  resolved: { host: 'localhost', port: 3000 },
+  schema: testSchema,
+};
+
+describe('config.init trail', () => {
+  describe('identity', () => {
+    test('has id "config.init"', () => {
+      expect(configInit.id).toBe('config.init');
+    });
+
+    test('has kind "trail"', () => {
+      expect(configInit.kind).toBe('trail');
+    });
+
+    test('has intent "write"', () => {
+      expect(configInit.intent).toBe('write');
+    });
+
+    test('has infrastructure metadata', () => {
+      expect(configInit.metadata).toEqual({ category: 'infrastructure' });
+    });
+
+    test('has output schema', () => {
+      expect(configInit.output).toBeDefined();
+    });
+
+    test('declares configService dependency', () => {
+      expect(configInit.services).toBeDefined();
+      expect(configInit.services?.length).toBe(1);
+    });
+  });
+
+  describe('examples', () => {
+    test('has at least one example', () => {
+      expect(configInit.examples?.length).toBeGreaterThanOrEqual(1);
+    });
+  });
+
+  describe('wired behavior', () => {
+    test('generates TOML output by default', async () => {
+      const ctx = buildCtx(testState);
+      const result = await configInit.run({ format: 'toml' }, ctx);
+
+      expect(result.isOk()).toBe(true);
+      const value = result.unwrap();
+      expect(value.format).toBe('toml');
+      expect(value.content).toContain('host');
+      expect(value.content).toContain('port');
+      expect(value.content.length).toBeGreaterThan(0);
+    });
+
+    test('generates JSON output when requested', async () => {
+      const ctx = buildCtx(testState);
+      const result = await configInit.run({ format: 'json' }, ctx);
+
+      expect(result.isOk()).toBe(true);
+      const value = result.unwrap();
+      expect(value.format).toBe('json');
+      expect(value.content).toContain('"host"');
+      expect(value.content).toContain('"port"');
+    });
+
+    test('generates YAML output when requested', async () => {
+      const ctx = buildCtx(testState);
+      const result = await configInit.run({ format: 'yaml' }, ctx);
+
+      expect(result.isOk()).toBe(true);
+      const value = result.unwrap();
+      expect(value.format).toBe('yaml');
+      expect(value.content).toContain('host:');
+    });
+
+    test('generates JSONC output when requested', async () => {
+      const ctx = buildCtx(testState);
+      const result = await configInit.run({ format: 'jsonc' }, ctx);
+
+      expect(result.isOk()).toBe(true);
+      const value = result.unwrap();
+      expect(value.format).toBe('jsonc');
+      expect(value.content).toContain('"host"');
+    });
+
+    test('output content is non-empty for schema with fields', async () => {
+      const ctx = buildCtx(testState);
+      const result = await configInit.run({ format: 'toml' }, ctx);
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap().content.trim().length).toBeGreaterThan(0);
+    });
+
+    test('returns content without writtenFiles when dir is not provided', async () => {
+      const ctx = buildCtx(testState);
+      const result = await configInit.run({ format: 'toml' }, ctx);
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap().writtenFiles).toBeUndefined();
+    });
+  });
+
+  describe('artifact generation', () => {
+    let tempDir: string;
+
+    const envSchema = z.object({
+      host: env(z.string(), 'APP_HOST').default('localhost'),
+      port: z.number().default(3000),
+    });
+
+    const envState: ConfigState = {
+      resolved: { host: 'localhost', port: 3000 },
+      schema: envSchema,
+    };
+
+    beforeEach(async () => {
+      tempDir = await mkdtemp(join(tmpdir(), 'trails-config-init-'));
+    });
+
+    afterEach(async () => {
+      await rm(tempDir, { force: true, recursive: true });
+    });
+
+    test('writes .schema.json when dir is provided', async () => {
+      const ctx = buildCtx(envState);
+      const result = await configInit.run(
+        { dir: tempDir, format: 'toml' },
+        ctx
+      );
+
+      expect(result.isOk()).toBe(true);
+      const value = result.unwrap();
+      expect(value.writtenFiles).toBeDefined();
+      expect(value.writtenFiles).toContainEqual(join(tempDir, '.schema.json'));
+
+      const schemaContent = await readFile(
+        join(tempDir, '.schema.json'),
+        'utf8'
+      );
+      const parsed = JSON.parse(schemaContent);
+      expect(parsed['$schema']).toBe(
+        'https://json-schema.org/draft/2020-12/schema'
+      );
+    });
+
+    test('writes .env.example when schema has env bindings', async () => {
+      const ctx = buildCtx(envState);
+      const result = await configInit.run(
+        { dir: tempDir, format: 'toml' },
+        ctx
+      );
+
+      expect(result.isOk()).toBe(true);
+      const value = result.unwrap();
+      expect(value.writtenFiles).toContainEqual(join(tempDir, '.env.example'));
+
+      const envContent = await readFile(join(tempDir, '.env.example'), 'utf8');
+      expect(envContent).toContain('APP_HOST');
+    });
+
+    test('still returns content alongside written files', async () => {
+      const ctx = buildCtx(envState);
+      const result = await configInit.run(
+        { dir: tempDir, format: 'json' },
+        ctx
+      );
+
+      expect(result.isOk()).toBe(true);
+      const value = result.unwrap();
+      expect(value.content.length).toBeGreaterThan(0);
+      expect(value.format).toBe('json');
+    });
+  });
+});

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

@@ -0,0 +1,53 @@
+import { describe, expect, test } from 'bun:test';
+import { Result } from '@ontrails/core';
+import type { TrailContext } from '@ontrails/core';
+import { z } from 'zod';
+
+import { configLayer } from '../config-layer.js';
+
+const stubTrail = {
+  description: undefined,
+  detours: undefined,
+  examples: undefined,
+  fields: undefined,
+  follow: [],
+  id: 'test.stub',
+  idempotent: undefined,
+  input: z.object({}),
+  intent: 'read' as const,
+  kind: 'trail' as const,
+  metadata: undefined,
+  output: undefined,
+  run: (_input: unknown, _ctx: TrailContext) => Result.ok({}),
+  services: [],
+};
+
+describe('configLayer', () => {
+  describe('identity', () => {
+    test('has name "config"', () => {
+      expect(configLayer.name).toBe('config');
+    });
+
+    test('has a description', () => {
+      expect(configLayer.description).toBeDefined();
+    });
+  });
+
+  describe('wrap', () => {
+    test('passes through to the base implementation', async () => {
+      const impl = (_input: unknown, _ctx: TrailContext) =>
+        Result.ok({ called: true });
+
+      const wrapped = configLayer.wrap(stubTrail, impl);
+      const ctx = {
+        cwd: '/tmp',
+        env: {},
+        workspaceRoot: '/tmp',
+      } as TrailContext;
+      const result = await wrapped({}, ctx);
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap()).toEqual({ called: true });
+    });
+  });
+});

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

@@ -0,0 +1,87 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { z } from 'zod';
+
+import { configService } from '../config-service.js';
+import type { ConfigState } from '../registry.js';
+import { clearConfigState, registerConfigState } from '../registry.js';
+
+/** Stub ServiceContext for create calls. */
+const stubSvcCtx = {
+  config: undefined,
+  cwd: '/tmp',
+  env: {},
+  workspaceRoot: '/tmp',
+};
+
+describe('configService', () => {
+  afterEach(() => {
+    clearConfigState();
+  });
+
+  describe('identity', () => {
+    test('has id "config"', () => {
+      expect(configService.id).toBe('config');
+    });
+
+    test('has kind "service"', () => {
+      expect(configService.kind).toBe('service');
+    });
+
+    test('has infrastructure metadata', () => {
+      expect(configService.metadata).toEqual({ category: 'infrastructure' });
+    });
+
+    test('has description', () => {
+      expect(configService.description).toBeDefined();
+    });
+  });
+
+  describe('mock', () => {
+    test('returns a ConfigState with empty schema and resolved', () => {
+      const value = configService.mock?.() as ConfigState;
+      expect(value).toBeDefined();
+      expect(value.resolved).toEqual({});
+      expect(value.schema).toBeDefined();
+    });
+  });
+
+  describe('create', () => {
+    test('returns Result.ok with registered ConfigState', async () => {
+      const schema = z.object({ port: z.number().default(3000) });
+      const state: ConfigState = { resolved: { port: 3000 }, schema };
+      registerConfigState(state);
+
+      const result = await configService.create(stubSvcCtx);
+
+      expect(result.isOk()).toBe(true);
+      const value = result.unwrap() as ConfigState;
+      expect(value.resolved).toEqual({ port: 3000 });
+      expect(value.schema).toBe(schema);
+    });
+
+    test('includes optional layer data when present', async () => {
+      const schema = z.object({ port: z.number() });
+      const state: ConfigState = {
+        base: { port: 8080 },
+        local: { port: 3000 },
+        resolved: { port: 3000 },
+        schema,
+      };
+      registerConfigState(state);
+
+      const result = await configService.create(stubSvcCtx);
+
+      expect(result.isOk()).toBe(true);
+      const value = result.unwrap() as ConfigState;
+      expect(value.base).toEqual({ port: 8080 });
+      expect(value.local).toEqual({ port: 3000 });
+    });
+
+    test('returns Result.err when no state is registered', async () => {
+      const result = await configService.create(stubSvcCtx);
+
+      expect(result.isErr()).toBe(true);
+      expect(result.error.message).toContain('Config state not registered');
+    });
+  });
+});

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

@@ -0,0 +1,263 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { z } from 'zod';
+
+import { defineConfig } from '../define-config.js';
+
+const schema = z.object({
+  debug: z.boolean().default(false),
+  host: z.string().default('localhost'),
+  port: z.number().default(3000),
+});
+
+type EnvKey = 'NODE_ENV' | 'TRAILS_ENV';
+
+interface EnvSnapshot {
+  readonly NODE_ENV: string | undefined;
+  readonly TRAILS_ENV: string | undefined;
+}
+
+const readEnvSnapshot = (): EnvSnapshot => ({
+  NODE_ENV: process.env.NODE_ENV,
+  TRAILS_ENV: process.env.TRAILS_ENV,
+});
+
+const setEnvVar = (key: EnvKey, value: string | undefined): void => {
+  if (value === undefined) {
+    if (key === 'NODE_ENV') {
+      delete process.env.NODE_ENV;
+    } else {
+      delete process.env.TRAILS_ENV;
+    }
+    return;
+  }
+  if (key === 'NODE_ENV') {
+    process.env.NODE_ENV = value;
+  } else {
+    process.env.TRAILS_ENV = value;
+  }
+};
+
+const restoreEnv = (snapshot: EnvSnapshot): void => {
+  setEnvVar('NODE_ENV', snapshot.NODE_ENV);
+  setEnvVar('TRAILS_ENV', snapshot.TRAILS_ENV);
+};
+
+describe('defineConfig', () => {
+  test('returns an object with schema, base, and loadouts', () => {
+    const base = { host: 'example.com' };
+    const loadouts = { production: { port: 443 } };
+
+    const config = defineConfig({ base, loadouts, schema });
+
+    expect(config.schema).toBe(schema);
+    expect(config.base).toBe(base);
+    expect(config.loadouts).toBe(loadouts);
+  });
+
+  test('resolve() uses TRAILS_ENV to select loadout', async () => {
+    const config = defineConfig({
+      base: { host: 'example.com' },
+      loadouts: {
+        production: { host: 'prod.example.com', port: 443 },
+        test: { host: 'test.example.com', port: 9999 },
+      },
+      schema,
+    });
+
+    const result = await config.resolve({
+      env: { TRAILS_ENV: 'production' },
+    });
+
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap().host).toBe('prod.example.com');
+    expect(result.unwrap().port).toBe(443);
+  });
+
+  test('resolve() with explicit loadout option overrides TRAILS_ENV', async () => {
+    const config = defineConfig({
+      base: { host: 'example.com' },
+      loadouts: {
+        production: { host: 'prod.example.com' },
+        test: { host: 'test.example.com' },
+      },
+      schema,
+    });
+
+    const result = await config.resolve({
+      env: { TRAILS_ENV: 'production' },
+      loadout: 'test',
+    });
+
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap().host).toBe('test.example.com');
+  });
+
+  test('envFromNodeEnv maps NODE_ENV to TRAILS_ENV when unset', async () => {
+    const config = defineConfig({
+      base: { host: 'example.com' },
+      envFromNodeEnv: true,
+      loadouts: {
+        production: { host: 'prod.example.com', port: 443 },
+      },
+      schema,
+    });
+
+    const result = await config.resolve({
+      env: { NODE_ENV: 'production' },
+    });
+
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap().host).toBe('prod.example.com');
+    expect(result.unwrap().port).toBe(443);
+  });
+
+  test('envFromNodeEnv does not mutate process.env', async () => {
+    const snapshot = readEnvSnapshot();
+    setEnvVar('TRAILS_ENV', undefined);
+    setEnvVar('NODE_ENV', 'production');
+
+    try {
+      const config = defineConfig({
+        base: { host: 'example.com' },
+        envFromNodeEnv: true,
+        loadouts: {
+          production: { host: 'prod.example.com', port: 443 },
+        },
+        schema,
+      });
+
+      const result = await config.resolve();
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap().host).toBe('prod.example.com');
+      expect(process.env.TRAILS_ENV).toBeUndefined();
+    } finally {
+      restoreEnv(snapshot);
+    }
+  });
+
+  test('envFromNodeEnv does not override explicit TRAILS_ENV', async () => {
+    const config = defineConfig({
+      base: { host: 'example.com' },
+      envFromNodeEnv: true,
+      loadouts: {
+        production: { host: 'prod.example.com' },
+        test: { host: 'test.example.com' },
+      },
+      schema,
+    });
+
+    const result = await config.resolve({
+      env: { NODE_ENV: 'production', TRAILS_ENV: 'test' },
+    });
+
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap().host).toBe('test.example.com');
+  });
+
+  test('test loadout works when TRAILS_ENV=test', async () => {
+    const config = defineConfig({
+      base: { port: 8080 },
+      loadouts: {
+        test: { debug: true, port: 0 },
+      },
+      schema,
+    });
+
+    const result = await config.resolve({
+      env: { TRAILS_ENV: 'test' },
+    });
+
+    expect(result.isOk()).toBe(true);
+    const value = result.unwrap();
+    expect(value.debug).toBe(true);
+    expect(value.port).toBe(0);
+  });
+
+  describe('local overrides', () => {
+    let tempDir: string;
+
+    beforeEach(async () => {
+      tempDir = await mkdtemp(join(tmpdir(), 'trails-define-config-'));
+    });
+
+    afterEach(async () => {
+      await rm(tempDir, { force: true, recursive: true });
+    });
+
+    test('applies local overrides from .trails/config/local.ts', async () => {
+      const configDir = join(tempDir, '.trails', 'config');
+      await mkdir(configDir, { recursive: true });
+      await Bun.write(
+        join(configDir, 'local.ts'),
+        'export default { port: 4444 };'
+      );
+
+      const config = defineConfig({
+        base: { host: 'example.com' },
+        schema,
+      });
+
+      const result = await config.resolve({
+        cwd: tempDir,
+        env: {},
+      });
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap().port).toBe(4444);
+    });
+
+    test('local overrides applied between loadout and env', async () => {
+      const configDir = join(tempDir, '.trails', 'config');
+      await mkdir(configDir, { recursive: true });
+      await Bun.write(
+        join(configDir, 'local.js'),
+        'export default { port: 5555 };'
+      );
+
+      const config = defineConfig({
+        base: { port: 8080 },
+        loadouts: {
+          dev: { port: 9090 },
+        },
+        schema,
+      });
+
+      // Local overrides should win over loadout (9090)
+      const result = await config.resolve({
+        cwd: tempDir,
+        env: { TRAILS_ENV: 'dev' },
+        loadout: 'dev',
+      });
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap().port).toBe(5555);
+    });
+
+    test('skips local overrides when TRAILS_ENV=test', async () => {
+      const configDir = join(tempDir, '.trails', 'config');
+      await mkdir(configDir, { recursive: true });
+      await Bun.write(
+        join(configDir, 'local.ts'),
+        'export default { port: 4444 };'
+      );
+
+      const config = defineConfig({
+        base: { port: 8080 },
+        schema,
+      });
+
+      const result = await config.resolve({
+        cwd: tempDir,
+        env: { TRAILS_ENV: 'test' },
+      });
+
+      expect(result.isOk()).toBe(true);
+      // Should NOT apply local overrides, so port stays at base 8080
+      expect(result.unwrap().port).toBe(8080);
+    });
+  });
+});