@cogenta/core 0.1.0

package/dist/cache/redis.js

@@ -0,0 +1,167 @@
+import { CogentaError } from '../errors/index.js';
+import { assertKey, decodeEntry, encodeEntry, expiryFrom, isExpired } from './entry.js';
+/**
+ * Loads the client if the host application installed it. Absent is a normal
+ * outcome, not an error: it is what makes the registry fall through to the file
+ * driver, and what lets `pnpm install` stay dependency-free (rule R1).
+ */
+export async function loadRedisModule() {
+    try {
+        return (await import('@redis/client'));
+    }
+    catch {
+        return null;
+    }
+}
+export function createRedisCache(options) {
+    const now = options.now ?? Date.now;
+    const prefix = options.prefix ?? 'cogenta:cache:';
+    const { client } = options;
+    const entryKey = (key) => `${prefix}e:${key}`;
+    const tagKey = (tag) => `${prefix}t:${tag}`;
+    async function readEntry(key) {
+        const raw = await client.get(entryKey(key));
+        if (raw === null)
+            return null;
+        try {
+            return decodeEntry(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    async function untag(key) {
+        const entry = await readEntry(key);
+        for (const tag of entry?.tags ?? [])
+            await client.sRem(tagKey(tag), [key]);
+    }
+    return {
+        get: async (key) => {
+            assertKey(key);
+            const entry = await readEntry(key);
+            if (entry === null)
+                return null;
+            // Expiry is checked here as well as delegated to Redis. Redis expires on
+            // wall-clock time it owns; checking the stored instant is what makes this
+            // driver behave identically to the others, contract suite included.
+            if (isExpired(entry.expiresAt, now())) {
+                await client.del([entryKey(key)]);
+                return null;
+            }
+            return entry.value;
+        },
+        set: async (key, value, setOptions) => {
+            assertKey(key);
+            const expiresAt = expiryFrom(setOptions?.ttl, now());
+            const tags = [...new Set(setOptions?.tags ?? [])];
+            const payload = encodeEntry(value, expiresAt, tags);
+            await untag(key);
+            // PX lets Redis reclaim the memory on its own clock. The authoritative
+            // check stays in `get`.
+            const ttlMs = setOptions?.ttl === undefined ? undefined : setOptions.ttl * 1000;
+            await client.set(entryKey(key), payload, ttlMs === undefined ? {} : { PX: ttlMs });
+            for (const tag of tags)
+                await client.sAdd(tagKey(tag), [key]);
+        },
+        delete: async (key) => {
+            assertKey(key);
+            await untag(key);
+            await client.del([entryKey(key)]);
+        },
+        invalidateTags: async (tags) => {
+            for (const tag of tags) {
+                const keys = await client.sMembers(tagKey(tag));
+                if (keys.length > 0)
+                    await client.del(keys.map(entryKey));
+                await client.del([tagKey(tag)]);
+            }
+        },
+        clear: async () => {
+            // SCAN, never FLUSHDB: this Redis may be serving other things, and a cache
+            // driver that wipes someone else's data is an incident, not a clear.
+            let cursor = '0';
+            do {
+                const result = await client.scan(cursor, { MATCH: `${prefix}*`, COUNT: 500 });
+                cursor = String(result.cursor);
+                if (result.keys.length > 0)
+                    await client.del(result.keys);
+            } while (cursor !== '0');
+        },
+    };
+}
+export function redisCacheDriver(options = {}) {
+    let client;
+    let url;
+    async function open(config) {
+        const module = await loadRedisModule();
+        if (module === null) {
+            throw new CogentaError({
+                code: 'DRIVER_INIT_FAILED',
+                message: 'The Redis cache driver needs the "@redis/client" package.',
+                hint: 'Run `pnpm add @redis/client`, or leave cache.driver unset to use the file cache.',
+            });
+        }
+        url = config.url;
+        const created = module.createClient(url === undefined ? {} : { url });
+        await created.connect();
+        return created;
+    }
+    return {
+        name: 'redis',
+        tier: 'optimal',
+        // Does Redis actually answer? Not "is a URL configured?" — the difference is
+        // what turns a graceful fallback into a startup crash.
+        available: async (config) => {
+            if (config.url === undefined)
+                return false;
+            try {
+                const probe = await open(config);
+                await probe.ping();
+                await probe.quit();
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        init: async (config) => {
+            client ??= await open(config);
+            return createRedisCache({ ...options, client });
+        },
+        dispose: async () => {
+            try {
+                await client?.quit();
+            }
+            catch {
+                // Shutdown must not fail because the connection already dropped.
+            }
+            client = undefined;
+        },
+        health: async () => {
+            if (client === undefined) {
+                return { status: 'down', driver: 'redis', tier: 'optimal', message: 'Not connected.' };
+            }
+            const startedAt = Date.now();
+            try {
+                await client.ping();
+                return {
+                    status: 'ok',
+                    driver: 'redis',
+                    tier: 'optimal',
+                    latencyMs: Date.now() - startedAt,
+                    // The URL is not reported: it routinely carries a password.
+                    message: 'Connected.',
+                };
+            }
+            catch (error) {
+                return {
+                    status: 'down',
+                    driver: 'redis',
+                    tier: 'optimal',
+                    message: error instanceof Error ? error.message : 'Redis did not answer.',
+                };
+            }
+        },
+    };
+}
+//# sourceMappingURL=redis.js.map

package/dist/cache/redis.js.map

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

package/dist/cache/types.d.ts

@@ -0,0 +1,37 @@
+export interface CacheSetOptions {
+    /** Seconds. Absent means "until invalidated". */
+    readonly ttl?: number;
+    /** Labels this entry belongs to, for bulk invalidation. */
+    readonly tags?: readonly string[];
+}
+/**
+ * A key/value cache.
+ *
+ * `invalidateTags` is **mandatory in every implementation**, including the ones
+ * with no server behind them. Content caching is only correct if a publish can
+ * drop every page that embedded the changed content; bolting that on later means
+ * rewriting each driver, so it is part of the interface from the first day.
+ *
+ * Values round-trip through serialisation in every driver, including `memory`.
+ * Handing back a live reference would let a caller mutate the cache by accident
+ * on one driver and not on another — the kind of divergence that only shows up
+ * in production, on the driver you did not develop against.
+ */
+export interface CacheDriver {
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, options?: CacheSetOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+    invalidateTags(tags: readonly string[]): Promise<void>;
+    clear(): Promise<void>;
+}
+/** The resolved `cache` section of the configuration. */
+export interface CacheConfig {
+    readonly driver?: string;
+    readonly url?: string | undefined;
+    readonly path?: string;
+}
+export interface CacheDriverOptions {
+    /** Injected so tests can expire entries without waiting. Milliseconds. */
+    readonly now?: () => number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cache/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/cache/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAClC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;IACtC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACtD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAED,yDAAyD;AACzD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAC5B"}

package/dist/cache/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/cache/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/cache/types.ts"],"names":[],"mappings":""}

package/dist/config/define-config.d.ts

@@ -0,0 +1,19 @@
+import type { CogentaConfigInput } from './types.js';
+/**
+ * Identity function whose only job is to give `cogenta.config.ts` full type
+ * checking and editor completion.
+ *
+ * ```ts
+ * import { defineConfig } from '@cogenta/core'
+ *
+ * export default defineConfig({
+ *   site: { name: 'My site', url: 'https://example.com' },
+ *   database: { url: process.env.DATABASE_URL ?? './.cogenta/site.db' },
+ * })
+ * ```
+ *
+ * Secrets are rejected here at compile time and again at startup: they belong
+ * in the environment, never in this file.
+ */
+export declare function defineConfig(config: CogentaConfigInput): CogentaConfigInput;
+//# sourceMappingURL=define-config.d.ts.map

package/dist/config/define-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-config.d.ts","sourceRoot":"","sources":["../../src/config/define-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAEpD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,kBAAkB,CAE3E"}

package/dist/config/define-config.js

@@ -0,0 +1,20 @@
+/**
+ * Identity function whose only job is to give `cogenta.config.ts` full type
+ * checking and editor completion.
+ *
+ * ```ts
+ * import { defineConfig } from '@cogenta/core'
+ *
+ * export default defineConfig({
+ *   site: { name: 'My site', url: 'https://example.com' },
+ *   database: { url: process.env.DATABASE_URL ?? './.cogenta/site.db' },
+ * })
+ * ```
+ *
+ * Secrets are rejected here at compile time and again at startup: they belong
+ * in the environment, never in this file.
+ */
+export function defineConfig(config) {
+    return config;
+}
+//# sourceMappingURL=define-config.js.map

package/dist/config/define-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-config.js","sourceRoot":"","sources":["../../src/config/define-config.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,YAAY,CAAC,MAA0B;IACrD,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/config/env.d.ts

@@ -0,0 +1,30 @@
+import type { Environment } from './types.js';
+/**
+ * Keys that must never appear in `cogenta.config.ts`, mapped to the environment
+ * variable that supplies them instead. The config file is committed to git; a
+ * secret in it is a secret in every clone, forever (rule R7).
+ */
+export declare const SECRET_KEYS: ReadonlyMap<string, string>;
+/**
+ * Overlays environment variables on top of the config file. Precedence is
+ * defaults → file → environment, so an operator can retarget a deployment
+ * without editing committed code.
+ *
+ * Secrets are deliberately *not* merged here: they are injected after
+ * validation, so they never pass through the schema or an error message.
+ */
+export declare function applyEnv(input: Record<string, unknown>, env: Environment): Record<string, unknown>;
+export interface EnvironmentSecrets {
+    readonly llmApiKey: string | undefined;
+    readonly storageAccessKeyId: string | undefined;
+    readonly storageSecretAccessKey: string | undefined;
+    /** Signs @cogenta/auth's MFA tickets. Never in the config file — there is no `auth` section to put it in, on purpose. */
+    readonly authSigningKey: string | undefined;
+}
+export declare function readSecrets(env: Environment): EnvironmentSecrets;
+/**
+ * Finds secrets written into the config file. Returns the dotted paths, never
+ * the values — an error message must not leak what it is complaining about.
+ */
+export declare function findSecretsInFile(input: Record<string, unknown>): readonly string[];
+//# sourceMappingURL=env.d.ts.map

package/dist/config/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/config/env.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAIlD,CAAA;AA8BF;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,GAAG,EAAE,WAAW,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA4EzB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/C,QAAQ,CAAC,sBAAsB,EAAE,MAAM,GAAG,SAAS,CAAA;IACnD,yHAAyH;IACzH,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAA;CAC5C;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,WAAW,GAAG,kBAAkB,CAOhE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,MAAM,EAAE,CAUnF"}

package/dist/config/env.js

@@ -0,0 +1,139 @@
+/**
+ * Keys that must never appear in `cogenta.config.ts`, mapped to the environment
+ * variable that supplies them instead. The config file is committed to git; a
+ * secret in it is a secret in every clone, forever (rule R7).
+ */
+export const SECRET_KEYS = new Map([
+    ['llm.apiKey', 'COGENTA_LLM_API_KEY'],
+    ['storage.accessKeyId', 'COGENTA_STORAGE_ACCESS_KEY_ID'],
+    ['storage.secretAccessKey', 'COGENTA_STORAGE_SECRET_ACCESS_KEY'],
+]);
+/** First variable that is set and not empty. An empty variable means "unset". */
+function read(env, ...names) {
+    for (const name of names) {
+        const value = env[name];
+        if (value !== undefined && value.trim() !== '')
+            return value.trim();
+    }
+    return undefined;
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Reads a section for merging. A section that exists but is not an object is
+ * returned untouched, so the schema can report "expected object" rather than a
+ * misleading list of missing fields.
+ */
+function section(input, key) {
+    const current = input[key];
+    if (current === undefined)
+        return {};
+    return isPlainObject(current) ? { ...current } : undefined;
+}
+function assign(target, key, value) {
+    if (value !== undefined)
+        target[key] = value;
+}
+/**
+ * Overlays environment variables on top of the config file. Precedence is
+ * defaults → file → environment, so an operator can retarget a deployment
+ * without editing committed code.
+ *
+ * Secrets are deliberately *not* merged here: they are injected after
+ * validation, so they never pass through the schema or an error message.
+ */
+export function applyEnv(input, env) {
+    const output = { ...input };
+    const site = section(output, 'site');
+    if (site !== undefined) {
+        assign(site, 'name', read(env, 'COGENTA_SITE_NAME'));
+        assign(site, 'url', read(env, 'COGENTA_SITE_URL'));
+        assign(site, 'defaultLocale', read(env, 'COGENTA_SITE_DEFAULT_LOCALE'));
+        const locales = read(env, 'COGENTA_SITE_LOCALES');
+        if (locales !== undefined) {
+            site['locales'] = locales
+                .split(',')
+                .map((locale) => locale.trim())
+                .filter((locale) => locale !== '');
+        }
+        output['site'] = site;
+    }
+    const database = section(output, 'database');
+    if (database !== undefined) {
+        assign(database, 'driver', read(env, 'COGENTA_DATABASE_DRIVER'));
+        assign(database, 'url', read(env, 'COGENTA_DATABASE_URL', 'DATABASE_URL'));
+        const poolSize = read(env, 'COGENTA_DATABASE_POOL_SIZE');
+        if (poolSize !== undefined)
+            database['poolSize'] = Number(poolSize);
+        output['database'] = database;
+    }
+    const cache = section(output, 'cache');
+    if (cache !== undefined) {
+        assign(cache, 'driver', read(env, 'COGENTA_CACHE_DRIVER'));
+        assign(cache, 'url', read(env, 'COGENTA_CACHE_URL', 'REDIS_URL'));
+        assign(cache, 'path', read(env, 'COGENTA_CACHE_PATH'));
+        output['cache'] = cache;
+    }
+    const queue = section(output, 'queue');
+    if (queue !== undefined) {
+        assign(queue, 'driver', read(env, 'COGENTA_QUEUE_DRIVER'));
+        assign(queue, 'url', read(env, 'COGENTA_QUEUE_URL', 'REDIS_URL'));
+        output['queue'] = queue;
+    }
+    const storage = section(output, 'storage');
+    if (storage !== undefined) {
+        assign(storage, 'driver', read(env, 'COGENTA_STORAGE_DRIVER'));
+        assign(storage, 'bucket', read(env, 'COGENTA_STORAGE_BUCKET'));
+        assign(storage, 'region', read(env, 'COGENTA_STORAGE_REGION'));
+        assign(storage, 'endpoint', read(env, 'COGENTA_STORAGE_ENDPOINT'));
+        assign(storage, 'path', read(env, 'COGENTA_STORAGE_PATH'));
+        assign(storage, 'baseUrl', read(env, 'COGENTA_STORAGE_BASE_URL'));
+        output['storage'] = storage;
+    }
+    // The LLM section only comes into existence if someone asked for one: with no
+    // provider configured, everything works except the agents (rule R2).
+    const llmProvider = read(env, 'COGENTA_LLM_PROVIDER');
+    const llm = section(output, 'llm');
+    if (llm !== undefined && (output['llm'] !== undefined || llmProvider !== undefined)) {
+        assign(llm, 'provider', llmProvider);
+        assign(llm, 'model', read(env, 'COGENTA_LLM_MODEL'));
+        assign(llm, 'baseUrl', read(env, 'COGENTA_LLM_BASE_URL'));
+        output['llm'] = llm;
+    }
+    const embeddings = section(output, 'embeddings');
+    if (embeddings !== undefined) {
+        assign(embeddings, 'provider', read(env, 'COGENTA_EMBEDDINGS_PROVIDER'));
+        assign(embeddings, 'model', read(env, 'COGENTA_EMBEDDINGS_MODEL'));
+        const dimensions = read(env, 'COGENTA_EMBEDDINGS_DIMENSIONS');
+        if (dimensions !== undefined)
+            embeddings['dimensions'] = Number(dimensions);
+        output['embeddings'] = embeddings;
+    }
+    return output;
+}
+export function readSecrets(env) {
+    return {
+        llmApiKey: read(env, 'COGENTA_LLM_API_KEY'),
+        storageAccessKeyId: read(env, 'COGENTA_STORAGE_ACCESS_KEY_ID'),
+        storageSecretAccessKey: read(env, 'COGENTA_STORAGE_SECRET_ACCESS_KEY'),
+        authSigningKey: read(env, 'COGENTA_AUTH_SIGNING_KEY'),
+    };
+}
+/**
+ * Finds secrets written into the config file. Returns the dotted paths, never
+ * the values — an error message must not leak what it is complaining about.
+ */
+export function findSecretsInFile(input) {
+    const found = [];
+    for (const path of SECRET_KEYS.keys()) {
+        const [sectionName, key] = path.split('.');
+        if (sectionName === undefined || key === undefined)
+            continue;
+        const target = input[sectionName];
+        if (isPlainObject(target) && target[key] !== undefined)
+            found.push(path);
+    }
+    return found;
+}
+//# sourceMappingURL=env.js.map

package/dist/config/env.js.map

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

package/dist/config/index.d.ts

@@ -0,0 +1,7 @@
+export { defineConfig } from './define-config.js';
+export type { LoadConfigOptions, LoadedConfig } from './load-config.js';
+export { CONFIG_FILE_NAMES, findConfigFile, loadConfig } from './load-config.js';
+export { resolveConfig } from './resolve-config.js';
+export type { CacheDriverName, CogentaConfig, CogentaConfigInput, DatabaseDriverName, EmbeddingsProvider, Environment, QueueDriverName, StorageDriverName, } from './types.js';
+export { CACHE_DRIVERS, DATABASE_DRIVERS, EMBEDDINGS_PROVIDERS, QUEUE_DRIVERS, STORAGE_DRIVERS, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACvE,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAChF,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,YAAY,EACV,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,iBAAiB,GAClB,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,oBAAoB,EACpB,aAAa,EACb,eAAe,GAChB,MAAM,YAAY,CAAA"}

package/dist/config/index.js

@@ -0,0 +1,5 @@
+export { defineConfig } from './define-config.js';
+export { CONFIG_FILE_NAMES, findConfigFile, loadConfig } from './load-config.js';
+export { resolveConfig } from './resolve-config.js';
+export { CACHE_DRIVERS, DATABASE_DRIVERS, EMBEDDINGS_PROVIDERS, QUEUE_DRIVERS, STORAGE_DRIVERS, } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEjD,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAChF,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAWnD,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,oBAAoB,EACpB,aAAa,EACb,eAAe,GAChB,MAAM,YAAY,CAAA"}

package/dist/config/load-config.d.ts

@@ -0,0 +1,30 @@
+import type { CogentaConfig, Environment } from './types.js';
+/** Checked in order, so a TypeScript config wins over a compiled one. */
+export declare const CONFIG_FILE_NAMES: readonly ['cogenta.config.ts', 'cogenta.config.mts', 'cogenta.config.js', 'cogenta.config.mjs'];
+/**
+ * Walks up from `cwd` looking for a config file, the way a package manager
+ * looks for a lockfile. Running the CLI from a subdirectory of a project is
+ * normal, and failing there would be a papercut on every single use.
+ */
+export declare function findConfigFile(cwd?: string): Promise<string | null>;
+export interface LoadConfigOptions {
+    readonly cwd?: string;
+    readonly env?: Environment;
+    /** Skip the search and load exactly this file. */
+    readonly path?: string;
+}
+export interface LoadedConfig {
+    readonly config: CogentaConfig;
+    /** Null when the configuration came from the environment alone. */
+    readonly path: string | null;
+}
+/**
+ * Finds, imports and resolves the configuration.
+ *
+ * A missing config file is **not** an error: an environment with
+ * `COGENTA_SITE_URL` and `DATABASE_URL` set is a legitimate way to run, and it
+ * is how a container is usually configured. What fails is a configuration that
+ * cannot produce a valid result, and it fails naming the fields.
+ */
+export declare function loadConfig(options?: LoadConfigOptions): Promise<LoadedConfig>;
+//# sourceMappingURL=load-config.d.ts.map

package/dist/config/load-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-config.d.ts","sourceRoot":"","sources":["../../src/config/load-config.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE5D,yEAAyE;AACzE,eAAO,MAAM,iBAAiB,YAC5B,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,CACZ,CAAA;AAWV;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,GAAG,GAAE,MAAsB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAaxF;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,WAAW,CAAA;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAC7B;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,YAAY,CAAC,CAkCvF"}

package/dist/config/load-config.js

@@ -0,0 +1,83 @@
+import { access } from 'node:fs/promises';
+import { dirname, join, resolve as resolvePath } from 'node:path';
+import process from 'node:process';
+import { pathToFileURL } from 'node:url';
+import { CogentaError } from '../errors/index.js';
+import { resolveConfig } from './resolve-config.js';
+/** Checked in order, so a TypeScript config wins over a compiled one. */
+export const CONFIG_FILE_NAMES = [
+    'cogenta.config.ts',
+    'cogenta.config.mts',
+    'cogenta.config.js',
+    'cogenta.config.mjs',
+];
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Walks up from `cwd` looking for a config file, the way a package manager
+ * looks for a lockfile. Running the CLI from a subdirectory of a project is
+ * normal, and failing there would be a papercut on every single use.
+ */
+export async function findConfigFile(cwd = process.cwd()) {
+    let directory = resolvePath(cwd);
+    for (;;) {
+        for (const name of CONFIG_FILE_NAMES) {
+            const candidate = join(directory, name);
+            if (await exists(candidate))
+                return candidate;
+        }
+        const parent = dirname(directory);
+        if (parent === directory)
+            return null;
+        directory = parent;
+    }
+}
+/**
+ * Finds, imports and resolves the configuration.
+ *
+ * A missing config file is **not** an error: an environment with
+ * `COGENTA_SITE_URL` and `DATABASE_URL` set is a legitimate way to run, and it
+ * is how a container is usually configured. What fails is a configuration that
+ * cannot produce a valid result, and it fails naming the fields.
+ */
+export async function loadConfig(options = {}) {
+    const env = options.env ?? process.env;
+    const path = options.path ?? (await findConfigFile(options.cwd));
+    if (path === null)
+        return { config: resolveConfig({}, env), path: null };
+    let module;
+    try {
+        module = (await import(pathToFileURL(path).href));
+    }
+    catch (error) {
+        throw new CogentaError({
+            code: 'CONFIG_LOAD_FAILED',
+            message: `Could not load ${path}: ${error instanceof Error ? error.message : String(error)}`,
+            hint: path.endsWith('.ts')
+                ? 'A TypeScript config needs a Node runtime that strips types, which means Node 22.18 or later. Rename it to cogenta.config.mjs if you are on an older one.'
+                : 'Check the file for a syntax error, and that every import it uses is installed.',
+            cause: error,
+            details: { path },
+        });
+    }
+    if (module.default === undefined) {
+        throw new CogentaError({
+            code: 'CONFIG_INVALID',
+            message: `${path} has no default export.`,
+            hint: 'Export the configuration as the default: `export default defineConfig({ … })`.',
+            details: { path },
+        });
+    }
+    // Relative paths in the file are relative to the file, not to the shell's
+    // working directory: running a command from a subdirectory must reach the same
+    // database, cache and media as running it from the project root.
+    return { config: resolveConfig(module.default, env, dirname(path)), path };
+}
+//# sourceMappingURL=load-config.js.map

package/dist/config/load-config.js.map

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

package/dist/config/resolve-config.d.ts

@@ -0,0 +1,14 @@
+import { type CogentaConfig, type Environment } from './types.js';
+/**
+ * Turns whatever was written in a config file into the fully resolved
+ * configuration the rest of Cogenta consumes.
+ *
+ * Precedence is defaults → file → environment. An invalid configuration fails
+ * here, at startup, naming every offending field at once — never three requests
+ * later with a stack trace.
+ *
+ * `baseDir` is the directory of the config file, when there was one. Relative
+ * paths are resolved against it.
+ */
+export declare function resolveConfig(input: unknown, env?: Environment, baseDir?: string): CogentaConfig;
+//# sourceMappingURL=resolve-config.d.ts.map

package/dist/config/resolve-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-config.d.ts","sourceRoot":"","sources":["../../src/config/resolve-config.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,aAAa,EAGlB,KAAK,WAAW,EACjB,MAAM,YAAY,CAAA;AAoDnB;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,EACd,GAAG,GAAE,WAAyB,EAC9B,OAAO,CAAC,EAAE,MAAM,GACf,aAAa,CAyFf"}