@ontrails/config 1.0.0-beta.13 → 1.0.0-beta.15

package/src/__tests__/compose.test.ts

@@ -2,57 +2,57 @@ import { describe, expect, test } from 'bun:test';
 
 import { z } from 'zod';
 
-import { collectProvisionConfigs } from '../compose.js';
+import { collectResourceConfigs } from '../compose.js';
 
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
 
-describe('collectProvisionConfigs', () => {
-  test('extracts config schemas from provisions that declare them', () => {
+describe('collectResourceConfigs', () => {
+  test('extracts config schemas from resources that declare them', () => {
     const dbSchema = z.object({ url: z.string().url() });
     const cacheSchema = z.object({ ttl: z.number() });
 
-    const provisions = [
+    const resources = [
       { config: dbSchema, id: 'db.main' },
       { config: cacheSchema, id: 'cache.main' },
     ];
 
-    const entries = collectProvisionConfigs(provisions);
+    const entries = collectResourceConfigs(resources);
 
     expect(entries).toHaveLength(2);
-    expect(entries[0]).toEqual({ provisionId: 'db.main', schema: dbSchema });
+    expect(entries[0]).toEqual({ resourceId: 'db.main', schema: dbSchema });
     expect(entries[1]).toEqual({
-      provisionId: 'cache.main',
+      resourceId: 'cache.main',
       schema: cacheSchema,
     });
   });
 
-  test('excludes provisions without config', () => {
+  test('excludes resources without config', () => {
     const schema = z.object({ url: z.string() });
 
-    const provisions = [
+    const resources = [
       { config: schema, id: 'db.main' },
       { id: 'counter.main' },
       { config: undefined, id: 'logger.main' },
     ];
 
-    const entries = collectProvisionConfigs(provisions);
+    const entries = collectResourceConfigs(resources);
 
     expect(entries).toHaveLength(1);
-    expect(entries[0]?.provisionId).toBe('db.main');
+    expect(entries[0]?.resourceId).toBe('db.main');
   });
 
-  test('returns empty array when no provisions have config', () => {
-    const provisions = [{ id: 'counter.main' }, { id: 'logger.main' }];
+  test('returns empty array when no resources have config', () => {
+    const resources = [{ id: 'counter.main' }, { id: 'logger.main' }];
 
-    const entries = collectProvisionConfigs(provisions);
+    const entries = collectResourceConfigs(resources);
 
     expect(entries).toEqual([]);
   });
 
   test('returns empty array for empty input', () => {
-    const entries = collectProvisionConfigs([]);
+    const entries = collectResourceConfigs([]);
 
     expect(entries).toEqual([]);
   });

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

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test';
-import { createProvisionLookup } from '@ontrails/core';
+import { createResourceLookup } from '@ontrails/core';
 import type { TrailContext } from '@ontrails/core';
 import { z } from 'zod';
 
@@ -7,7 +7,7 @@ import { configCheck } from '../trails/config-check.js';
 import type { ConfigState } from '../registry.js';
 
 /**
- * Build a TrailContext with configProvision resolved in extensions.
+ * Build a TrailContext with configResource resolved in extensions.
  */
 const buildCtx = (state: ConfigState): TrailContext => {
   const extensions = { config: state };
@@ -16,13 +16,13 @@ const buildCtx = (state: ConfigState): TrailContext => {
     cwd: '/tmp',
     env: {},
     extensions,
-    provision: undefined as unknown as TrailContext['provision'],
     requestId: 'test',
+    resource: undefined as unknown as TrailContext['resource'],
     workspaceRoot: '/tmp',
   };
   const withLookup = {
     ...ctx,
-    provision: createProvisionLookup(() => withLookup),
+    resource: createResourceLookup(() => withLookup),
   };
   return withLookup;
 };
@@ -49,9 +49,9 @@ describe('config.check trail', () => {
       expect(configCheck.output).toBeDefined();
     });
 
-    test('declares configProvision dependency', () => {
-      expect(configCheck.provisions).toBeDefined();
-      expect(configCheck.provisions?.length).toBe(1);
+    test('declares configResource dependency', () => {
+      expect(configCheck.resources).toBeDefined();
+      expect(configCheck.resources?.length).toBe(1);
     });
   });
 

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

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test';
-import { createProvisionLookup } from '@ontrails/core';
+import { createResourceLookup } from '@ontrails/core';
 import type { TrailContext } from '@ontrails/core';
 import { z } from 'zod';
 
@@ -8,7 +8,7 @@ import { env, secret } from '../extensions.js';
 import type { ConfigState } from '../registry.js';
 
 /**
- * Build a TrailContext with configProvision resolved in extensions.
+ * Build a TrailContext with configResource resolved in extensions.
  */
 const buildCtx = (state: ConfigState): TrailContext => {
   const extensions = { config: state };
@@ -17,13 +17,13 @@ const buildCtx = (state: ConfigState): TrailContext => {
     cwd: '/tmp',
     env: {},
     extensions,
-    provision: undefined as unknown as TrailContext['provision'],
     requestId: 'test',
+    resource: undefined as unknown as TrailContext['resource'],
     workspaceRoot: '/tmp',
   };
   const withLookup = {
     ...ctx,
-    provision: createProvisionLookup(() => withLookup),
+    resource: createResourceLookup(() => withLookup),
   };
   return withLookup;
 };
@@ -50,9 +50,9 @@ describe('config.describe trail', () => {
       expect(configDescribe.output).toBeDefined();
     });
 
-    test('declares configProvision dependency', () => {
-      expect(configDescribe.provisions).toBeDefined();
-      expect(configDescribe.provisions?.length).toBe(1);
+    test('declares configResource dependency', () => {
+      expect(configDescribe.resources).toBeDefined();
+      expect(configDescribe.resources?.length).toBe(1);
     });
   });
 

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

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test';
-import { createProvisionLookup } from '@ontrails/core';
+import { createResourceLookup } from '@ontrails/core';
 import type { TrailContext } from '@ontrails/core';
 import { z } from 'zod';
 
@@ -8,7 +8,7 @@ import { env } from '../extensions.js';
 import type { ConfigState } from '../registry.js';
 
 /**
- * Build a TrailContext with configProvision resolved in extensions.
+ * Build a TrailContext with configResource resolved in extensions.
  */
 const buildCtx = (state: ConfigState): TrailContext => {
   const extensions = { config: state };
@@ -17,13 +17,13 @@ const buildCtx = (state: ConfigState): TrailContext => {
     cwd: '/tmp',
     env: {},
     extensions,
-    provision: undefined as unknown as TrailContext['provision'],
     requestId: 'test',
+    resource: undefined as unknown as TrailContext['resource'],
     workspaceRoot: '/tmp',
   };
   const withLookup = {
     ...ctx,
-    provision: createProvisionLookup(() => withLookup),
+    resource: createResourceLookup(() => withLookup),
   };
   return withLookup;
 };
@@ -50,9 +50,9 @@ describe('config.explain trail', () => {
       expect(configExplain.output).toBeDefined();
     });
 
-    test('declares configProvision dependency', () => {
-      expect(configExplain.provisions).toBeDefined();
-      expect(configExplain.provisions?.length).toBe(1);
+    test('declares configResource dependency', () => {
+      expect(configExplain.resources).toBeDefined();
+      expect(configExplain.resources?.length).toBe(1);
     });
   });
 

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

@@ -2,7 +2,7 @@ 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 { createProvisionLookup } from '@ontrails/core';
+import { createResourceLookup } from '@ontrails/core';
 import type { TrailContext } from '@ontrails/core';
 import { z } from 'zod';
 
@@ -11,7 +11,7 @@ import type { ConfigState } from '../registry.js';
 import { configInit } from '../trails/config-init.js';
 
 /**
- * Build a TrailContext with configProvision resolved in extensions.
+ * Build a TrailContext with configResource resolved in extensions.
  */
 const buildCtx = (state: ConfigState): TrailContext => {
   const extensions = { config: state };
@@ -20,13 +20,13 @@ const buildCtx = (state: ConfigState): TrailContext => {
     cwd: '/tmp',
     env: {},
     extensions,
-    provision: undefined as unknown as TrailContext['provision'],
     requestId: 'test',
+    resource: undefined as unknown as TrailContext['resource'],
     workspaceRoot: '/tmp',
   };
   const withLookup = {
     ...ctx,
-    provision: createProvisionLookup(() => withLookup),
+    resource: createResourceLookup(() => withLookup),
   };
   return withLookup;
 };
@@ -63,9 +63,9 @@ describe('config.init trail', () => {
       expect(configInit.output).toBeDefined();
     });
 
-    test('declares configProvision dependency', () => {
-      expect(configInit.provisions).toBeDefined();
-      expect(configInit.provisions?.length).toBe(1);
+    test('declares configResource dependency', () => {
+      expect(configInit.resources).toBeDefined();
+      expect(configInit.resources?.length).toBe(1);
     });
   });
 

package/src/__tests__/{config-provision.test.ts → config-resource.test.ts}

@@ -1,11 +1,11 @@
 import { afterEach, describe, expect, test } from 'bun:test';
 import { z } from 'zod';
 
-import { configProvision } from '../config-provision.js';
+import { configResource } from '../config-resource.js';
 import type { ConfigState } from '../registry.js';
 import { clearConfigState, registerConfigState } from '../registry.js';
 
-/** Stub ProvisionContext for create calls. */
+/** Stub ResourceContext for create calls. */
 const stubSvcCtx = {
   config: undefined,
   cwd: '/tmp',
@@ -13,32 +13,32 @@ const stubSvcCtx = {
   workspaceRoot: '/tmp',
 };
 
-describe('configProvision', () => {
+describe('configResource', () => {
   afterEach(() => {
     clearConfigState();
   });
 
   describe('identity', () => {
     test('has id "config"', () => {
-      expect(configProvision.id).toBe('config');
+      expect(configResource.id).toBe('config');
     });
 
-    test('has kind "provision"', () => {
-      expect(configProvision.kind).toBe('provision');
+    test('has kind "resource"', () => {
+      expect(configResource.kind).toBe('resource');
     });
 
     test('has infrastructure meta', () => {
-      expect(configProvision.meta).toEqual({ category: 'infrastructure' });
+      expect(configResource.meta).toEqual({ category: 'infrastructure' });
     });
 
     test('has description', () => {
-      expect(configProvision.description).toBeDefined();
+      expect(configResource.description).toBeDefined();
     });
   });
 
   describe('mock', () => {
     test('returns a ConfigState with empty schema and resolved', () => {
-      const value = configProvision.mock?.() as ConfigState;
+      const value = configResource.mock?.() as ConfigState;
       expect(value).toBeDefined();
       expect(value.resolved).toEqual({});
       expect(value.schema).toBeDefined();
@@ -51,7 +51,7 @@ describe('configProvision', () => {
       const state: ConfigState = { resolved: { port: 3000 }, schema };
       registerConfigState(state);
 
-      const result = await configProvision.create(stubSvcCtx);
+      const result = await configResource.create(stubSvcCtx);
 
       expect(result.isOk()).toBe(true);
       const value = result.unwrap() as ConfigState;
@@ -69,7 +69,7 @@ describe('configProvision', () => {
       };
       registerConfigState(state);
 
-      const result = await configProvision.create(stubSvcCtx);
+      const result = await configResource.create(stubSvcCtx);
 
       expect(result.isOk()).toBe(true);
       const value = result.unwrap() as ConfigState;
@@ -78,7 +78,7 @@ describe('configProvision', () => {
     });
 
     test('returns Result.err when no state is registered', async () => {
-      const result = await configProvision.create(stubSvcCtx);
+      const result = await configResource.create(stubSvcCtx);
 
       expect(result.isErr()).toBe(true);
       expect(result.error.message).toContain('Config state not registered');

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

@@ -46,21 +46,21 @@ const restoreEnv = (snapshot: EnvSnapshot): void => {
 };
 
 describe('defineConfig', () => {
-  test('returns an object with schema, base, and loadouts', () => {
+  test('returns an object with schema, base, and profiles', () => {
     const base = { host: 'example.com' };
-    const loadouts = { production: { port: 443 } };
+    const profiles = { production: { port: 443 } };
 
-    const config = defineConfig({ base, loadouts, schema });
+    const config = defineConfig({ base, profiles, schema });
 
     expect(config.schema).toBe(schema);
     expect(config.base).toBe(base);
-    expect(config.loadouts).toBe(loadouts);
+    expect(config.profiles).toBe(profiles);
   });
 
-  test('resolve() uses TRAILS_ENV to select loadout', async () => {
+  test('resolve() uses TRAILS_ENV to select profile', async () => {
     const config = defineConfig({
       base: { host: 'example.com' },
-      loadouts: {
+      profiles: {
         production: { host: 'prod.example.com', port: 443 },
         test: { host: 'test.example.com', port: 9999 },
       },
@@ -76,10 +76,10 @@ describe('defineConfig', () => {
     expect(result.unwrap().port).toBe(443);
   });
 
-  test('resolve() with explicit loadout option overrides TRAILS_ENV', async () => {
+  test('resolve() with explicit profile option overrides TRAILS_ENV', async () => {
     const config = defineConfig({
       base: { host: 'example.com' },
-      loadouts: {
+      profiles: {
         production: { host: 'prod.example.com' },
         test: { host: 'test.example.com' },
       },
@@ -88,7 +88,7 @@ describe('defineConfig', () => {
 
     const result = await config.resolve({
       env: { TRAILS_ENV: 'production' },
-      loadout: 'test',
+      profile: 'test',
     });
 
     expect(result.isOk()).toBe(true);
@@ -99,7 +99,7 @@ describe('defineConfig', () => {
     const config = defineConfig({
       base: { host: 'example.com' },
       envFromNodeEnv: true,
-      loadouts: {
+      profiles: {
         production: { host: 'prod.example.com', port: 443 },
       },
       schema,
@@ -123,7 +123,7 @@ describe('defineConfig', () => {
       const config = defineConfig({
         base: { host: 'example.com' },
         envFromNodeEnv: true,
-        loadouts: {
+        profiles: {
           production: { host: 'prod.example.com', port: 443 },
         },
         schema,
@@ -143,7 +143,7 @@ describe('defineConfig', () => {
     const config = defineConfig({
       base: { host: 'example.com' },
       envFromNodeEnv: true,
-      loadouts: {
+      profiles: {
         production: { host: 'prod.example.com' },
         test: { host: 'test.example.com' },
       },
@@ -158,10 +158,10 @@ describe('defineConfig', () => {
     expect(result.unwrap().host).toBe('test.example.com');
   });
 
-  test('test loadout works when TRAILS_ENV=test', async () => {
+  test('test profile works when TRAILS_ENV=test', async () => {
     const config = defineConfig({
       base: { port: 8080 },
-      loadouts: {
+      profiles: {
         test: { debug: true, port: 0 },
       },
       schema,
@@ -177,6 +177,12 @@ describe('defineConfig', () => {
     expect(value.port).toBe(0);
   });
 
+  test('inherits the canonical appConfig format list, including jsonc', () => {
+    const config = defineConfig({ schema });
+
+    expect(config.formats).toEqual(['toml', 'json', 'jsonc', 'yaml']);
+  });
+
   describe('local overrides', () => {
     let tempDir: string;
 
@@ -210,7 +216,7 @@ describe('defineConfig', () => {
       expect(result.unwrap().port).toBe(4444);
     });
 
-    test('local overrides applied between loadout and env', async () => {
+    test('local overrides applied between profile and env', async () => {
       const configDir = join(tempDir, '.trails', 'config');
       await mkdir(configDir, { recursive: true });
       await Bun.write(
@@ -220,17 +226,17 @@ describe('defineConfig', () => {
 
       const config = defineConfig({
         base: { port: 8080 },
-        loadouts: {
+        profiles: {
           dev: { port: 9090 },
         },
         schema,
       });
 
-      // Local overrides should win over loadout (9090)
+      // Local overrides should win over profile (9090)
       const result = await config.resolve({
         cwd: tempDir,
         env: { TRAILS_ENV: 'dev' },
-        loadout: 'dev',
+        profile: 'dev',
       });
 
       expect(result.isOk()).toBe(true);

package/src/__tests__/{describe.test.ts → derive-fields.test.ts}

@@ -2,9 +2,9 @@ import { describe, expect, test } from 'bun:test';
 import { z } from 'zod';
 
 import { deprecated, env, secret } from '../extensions.js';
-import { describeConfig } from '../describe.js';
+import { deriveConfigFields } from '../derive-fields.js';
 
-describe('describeConfig', () => {
+describe('deriveConfigFields', () => {
   describe('basic field descriptions', () => {
     test('returns path, type, and required for each field', () => {
       const schema = z.object({
@@ -13,7 +13,7 @@ describe('describeConfig', () => {
         port: z.number(),
       });
 
-      const fields = describeConfig(schema);
+      const fields = deriveConfigFields(schema);
 
       expect(fields).toHaveLength(3);
       const host = fields.find((f) => f.path === 'host');
@@ -32,7 +32,7 @@ describe('describeConfig', () => {
         host: z.string().describe('The server hostname'),
       });
 
-      const fields = describeConfig(schema);
+      const fields = deriveConfigFields(schema);
       const host = fields.find((f) => f.path === 'host');
       expect(host?.description).toBe('The server hostname');
     });
@@ -47,7 +47,7 @@ describe('describeConfig', () => {
         ),
       });
 
-      const fields = describeConfig(schema);
+      const fields = deriveConfigFields(schema);
 
       const apiKey = fields.find((f) => f.path === 'apiKey');
       expect(apiKey?.env).toBe('API_KEY');
@@ -65,7 +65,7 @@ describe('describeConfig', () => {
         port: z.number().default(3000),
       });
 
-      const fields = describeConfig(schema);
+      const fields = deriveConfigFields(schema);
 
       const port = fields.find((f) => f.path === 'port');
       expect(port?.default).toBe(3000);
@@ -85,7 +85,7 @@ describe('describeConfig', () => {
         }),
       });
 
-      const fields = describeConfig(schema);
+      const fields = deriveConfigFields(schema);
 
       const dbHost = fields.find((f) => f.path === 'db.host');
       expect(dbHost?.type).toBe('string');
@@ -106,7 +106,7 @@ describe('describeConfig', () => {
           .optional(),
       });
 
-      const fields = describeConfig(schema);
+      const fields = deriveConfigFields(schema);
 
       expect(fields).toEqual([
         expect.objectContaining({ path: 'db.host', required: true }),
@@ -121,7 +121,7 @@ describe('describeConfig', () => {
         env: z.enum(['development', 'production', 'test']),
       });
 
-      const fields = describeConfig(schema);
+      const fields = deriveConfigFields(schema);
       const envField = fields.find((f) => f.path === 'env');
       expect(envField?.type).toBe('enum');
       expect(envField?.constraints?.values).toEqual([
@@ -136,7 +136,7 @@ describe('describeConfig', () => {
         port: z.number().min(1).max(65_535),
       });
 
-      const fields = describeConfig(schema);
+      const fields = deriveConfigFields(schema);
       const port = fields.find((f) => f.path === 'port');
       expect(port?.constraints?.min).toBe(1);
       expect(port?.constraints?.max).toBe(65_535);
@@ -150,7 +150,7 @@ describe('describeConfig', () => {
         nickname: z.string().optional(),
       });
 
-      const fields = describeConfig(schema);
+      const fields = deriveConfigFields(schema);
       const nickname = fields.find((f) => f.path === 'nickname');
       expect(nickname?.required).toBe(false);
     });

package/src/__tests__/{explain.test.ts → derive-provenance.test.ts}

@@ -2,7 +2,7 @@ import { describe, expect, test } from 'bun:test';
 import { z } from 'zod';
 
 import { env, secret } from '../extensions.js';
-import { explainConfig } from '../explain.js';
+import { deriveConfigProvenance } from '../derive-provenance.js';
 
 const schema = z.object({
   debug: z.boolean().default(false),
@@ -10,10 +10,10 @@ const schema = z.object({
   port: z.number().default(3000),
 });
 
-describe('explainConfig', () => {
+describe('deriveConfigProvenance', () => {
   describe('default source', () => {
     test('reports "default" when no other source provides value', () => {
-      const entries = explainConfig({
+      const entries = deriveConfigProvenance({
         resolved: { debug: false, host: 'localhost', port: 3000 },
         schema,
       });
@@ -26,7 +26,7 @@ describe('explainConfig', () => {
 
   describe('base overrides default', () => {
     test('reports "base" when base provides value', () => {
-      const entries = explainConfig({
+      const entries = deriveConfigProvenance({
         base: { host: 'base.example.com' },
         resolved: { debug: false, host: 'base.example.com', port: 3000 },
         schema,
@@ -38,27 +38,27 @@ describe('explainConfig', () => {
     });
   });
 
-  describe('loadout overrides base', () => {
-    test('reports "loadout" when loadout provides winning value', () => {
-      const entries = explainConfig({
+  describe('profile overrides base', () => {
+    test('reports "profile" when profile provides winning value', () => {
+      const entries = deriveConfigProvenance({
         base: { host: 'base.example.com' },
-        loadout: { host: 'loadout.example.com' },
-        resolved: { debug: false, host: 'loadout.example.com', port: 3000 },
+        profile: { host: 'profile.example.com' },
+        resolved: { debug: false, host: 'profile.example.com', port: 3000 },
         schema,
       });
 
       const host = entries.find((e) => e.path === 'host');
-      expect(host?.source).toBe('loadout');
-      expect(host?.value).toBe('loadout.example.com');
+      expect(host?.source).toBe('profile');
+      expect(host?.value).toBe('profile.example.com');
     });
   });
 
-  describe('local overrides loadout', () => {
+  describe('local overrides profile', () => {
     test('reports "local" when local provides winning value', () => {
-      const entries = explainConfig({
+      const entries = deriveConfigProvenance({
         base: { host: 'base.example.com' },
-        loadout: { host: 'loadout.example.com' },
         local: { host: 'local.example.com' },
+        profile: { host: 'profile.example.com' },
         resolved: { debug: false, host: 'local.example.com', port: 3000 },
         schema,
       });
@@ -75,7 +75,7 @@ describe('explainConfig', () => {
         port: z.number().default(3000),
       });
 
-      const entries = explainConfig({
+      const entries = deriveConfigProvenance({
         base: { host: 'base.example.com' },
         env: { APP_HOST: 'env.example.com' },
         resolved: { host: 'env.example.com', port: 3000 },
@@ -96,7 +96,7 @@ describe('explainConfig', () => {
           .optional(),
       });
 
-      const entries = explainConfig({
+      const entries = deriveConfigProvenance({
         env: { DB_HOST: 'env.example.com' },
         resolved: { db: { host: 'env.example.com' } },
         schema: envSchema,
@@ -115,7 +115,7 @@ describe('explainConfig', () => {
         host: z.string().default('localhost'),
       });
 
-      const entries = explainConfig({
+      const entries = deriveConfigProvenance({
         env: { API_KEY: 'super-secret-key' },
         resolved: { apiKey: 'super-secret-key', host: 'localhost' },
         schema: secretSchema,
@@ -127,7 +127,7 @@ describe('explainConfig', () => {
     });
 
     test('does not redact non-secret fields', () => {
-      const entries = explainConfig({
+      const entries = deriveConfigProvenance({
         resolved: { debug: false, host: 'localhost', port: 3000 },
         schema,
       });