@happyvertical/smrt-config 0.30.0

package/dist/index.d.ts

@@ -0,0 +1,1098 @@
+import { DomainKnowledgeConfig } from '@happyvertical/smrt-types';
+
+/**
+ * Reset all cached configuration state.
+ *
+ * Clears three independent caches:
+ * 1. `globalThis.__smrtConfigCache` — the merged config loaded by {@link loadConfig}.
+ * 2. The internal loader cache (`globalThis.__smrtLoaderCachedConfig`) and the
+ *    cosmiconfig explorer instance.
+ * 3. The runtime override store populated by {@link setConfig}.
+ *
+ * After calling this, {@link getConfig} returns `null` and a fresh
+ * {@link loadConfig} call will re-read from disk.
+ *
+ * WARNING: This is a global reset — it affects every module sharing the same
+ * runtime, not just the caller. Use with care outside of test teardown.
+ *
+ * @example
+ * ```ts
+ * afterEach(() => {
+ *   clearCache(); // reset between tests
+ * });
+ * ```
+ *
+ * @see {@link loadConfig}
+ * @see {@link setConfig}
+ */
+export declare function clearCache(): void;
+
+/**
+ * Reset the runtime configuration override store to an empty object.
+ *
+ * Called by {@link clearCache} in `index.ts` as part of a full cache reset.
+ * Useful in tests to ensure a clean state between cases.
+ *
+ * @see {@link setConfig}
+ */
+export declare function clearRuntimeConfig(): void;
+
+/**
+ * CLI package configuration.
+ *
+ * Placed under the `cli` key in `smrt.config.js`. Consumed by
+ * `@happyvertical/smrt-cli` for `smrt db:*` and migration commands.
+ *
+ * @example
+ * ```js
+ * export default defineConfig({
+ *   cli: {
+ *     database: { type: 'sqlite', url: 'file:./local.db' },
+ *     migrations: { mode: 'dynamic', directory: './migrations' },
+ *   },
+ * });
+ * ```
+ *
+ * @see {@link DatabaseConfig}
+ * @see {@link MigrationsConfig}
+ */
+export declare interface CliConfig {
+    /**
+     * Database connection settings
+     */
+    database?: DatabaseConfig;
+    /**
+     * Migration settings
+     */
+    migrations?: MigrationsConfig;
+    /**
+     * Required manifest/object/field/database-shape contract for schema commands.
+     */
+    schemaContract?: SchemaContractConfig;
+}
+
+/**
+ * Database connection configuration for CLI commands.
+ *
+ * Placed under `cli.database` in `smrt.config.js`. Used by
+ * `@happyvertical/smrt-cli` to connect for migration and inspection commands.
+ *
+ * @see {@link CliConfig}
+ */
+export declare interface DatabaseConfig {
+    /**
+     * Database type
+     *
+     * @default 'sqlite'
+     */
+    type?: 'sqlite' | 'postgres' | 'duckdb';
+    /**
+     * Database connection URL
+     *
+     * For SQLite: file path or ':memory:'
+     * For PostgreSQL: postgresql://user:pass@host:port/dbname
+     */
+    url?: string;
+}
+
+/**
+ * Type-safe helper for authoring `smrt.config.js` files.
+ *
+ * This is an identity function — it returns its argument unchanged. Its sole
+ * purpose is to provide TypeScript type-checking and IDE auto-completion when
+ * writing the config object literal.
+ *
+ * @param config - The config object to validate against {@link SmrtConfig}.
+ * @returns The same object, unchanged.
+ *
+ * @example
+ * ```js
+ * // smrt.config.js
+ * import { defineConfig } from '@happyvertical/smrt-config';
+ *
+ * export default defineConfig({
+ *   smrt: { logLevel: 'info' },
+ *   site: { name: 'My Site', ... },
+ * });
+ * ```
+ *
+ * @see {@link SmrtConfig}
+ * @see {@link loadConfig}
+ */
+export declare function defineConfig(config: SmrtConfig): SmrtConfig;
+
+/**
+ * Export configuration for static site generation.
+ *
+ * Placed under the `export` key in `smrt.config.js`. Controls how database
+ * records are exported to static files during SSG builds. Each additional
+ * key beyond `fieldExportDefault` and `format` defines a named export file.
+ *
+ * @example
+ * ```js
+ * export default defineConfig({
+ *   export: {
+ *     fieldExportDefault: true,
+ *     articles: { types: ['Article'], filters: { status: ['published'] } },
+ *     games: { types: ['Game'], orderBy: '-date', format: 'ndjson' },
+ *   },
+ * });
+ * ```
+ *
+ * @see {@link ExportFileConfig}
+ * @see {@link exportConfig}
+ */
+export declare interface ExportConfig {
+    /**
+     * Default export behavior for fields without explicit `exported` annotation
+     *
+     * - true: Export all fields by default (simpler, for most sites)
+     * - false: Only export fields with explicit `exported: true`
+     *
+     * @default true
+     */
+    fieldExportDefault?: boolean;
+    /**
+     * Default output format for all exports
+     * @default 'json'
+     */
+    format?: 'json' | 'ndjson' | 'csv' | 'sqlite';
+    /**
+     * Export file configurations
+     * Keys become filenames (e.g., 'contents' -> 'contents.json')
+     */
+    [filename: string]: ExportFileConfig | boolean | string | undefined;
+}
+
+/**
+ * Serialize a configuration object to a formatted string for SSG file output.
+ *
+ * By default, {@link sanitizeConfig} is applied before serialization to strip
+ * any keys that match secret patterns (API keys, passwords, tokens, etc.).
+ * Pass `includeSecrets: true` only in secured server-side contexts.
+ *
+ * @param config - Configuration object to export. Any JSON-serializable value.
+ * @param options - Format, indentation, and secret-inclusion options.
+ * @returns A JSON string, or an ES module string (`export default {...};\n`)
+ *   when `format: 'js'`.
+ *
+ * @example
+ * ```ts
+ * // Write a sanitized JSON export file for SSG
+ * const json = exportConfig(agentConfig);
+ * await fs.writeFile('./public/config.json', json);
+ * ```
+ *
+ * @example
+ * ```ts
+ * // ES module format (importable via `import config from './config.js'`)
+ * const js = exportConfig(agentConfig, { format: 'js' });
+ * ```
+ *
+ * @see {@link sanitizeConfig}
+ * @see {@link parseExportedConfig}
+ * @see {@link ExportConfigOptions}
+ */
+export declare function exportConfig(config: unknown, options?: ExportConfigOptions): string;
+
+/**
+ * Options accepted by {@link exportConfig}.
+ */
+export declare interface ExportConfigOptions {
+    /**
+     * Include secrets in the export (use with caution!)
+     * @default false
+     */
+    includeSecrets?: boolean;
+    /**
+     * Output format
+     * - 'json': Plain JSON format
+     * - 'js': ES module format (export default)
+     * @default 'json'
+     */
+    format?: 'json' | 'js';
+    /**
+     * Number of spaces for indentation
+     * @default 2
+     */
+    indent?: number;
+}
+
+/**
+ * Configuration for a single SSG export file.
+ *
+ * Each key in {@link ExportConfig} (besides `fieldExportDefault` and `format`)
+ * becomes the output filename. Records are queried from the database, filtered,
+ * ordered, and written to `{key}.json` (or the specified format).
+ *
+ * @example
+ * ```js
+ * export default defineConfig({
+ *   export: {
+ *     articles: {
+ *       types: ['Article'],
+ *       filters: { status: ['published'] },
+ *       orderBy: '-publishDate',
+ *       limit: 500,
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @see {@link ExportConfig}
+ * @see {@link ExportFilterValue}
+ */
+export declare interface ExportFileConfig {
+    /**
+     * SMRT object types to include in this export
+     * Uses className (e.g., 'MeetingRecap', 'Game')
+     */
+    types: string[];
+    /**
+     * Field whitelist - only export these fields
+     * If specified, overrides exclude and fieldExportDefault
+     */
+    include?: string[];
+    /**
+     * Field blacklist - exclude these fields
+     * Applied after schema-level exported: false check
+     */
+    exclude?: string[];
+    /**
+     * Filters to apply when querying records
+     * Keys are field names, values are filter conditions
+     *
+     * @example
+     * filters: {
+     *   status: ['published'],  // shorthand for status IN ('published')
+     *   publish_date: { gte: '2025-01-01' },
+     *   council_slug: ['town-of-bentley'],
+     * }
+     */
+    filters?: Record<string, string[] | number[] | ExportFilterValue>;
+    /**
+     * Output format for this file
+     * @default 'json'
+     */
+    format?: 'json' | 'ndjson' | 'csv' | 'sqlite';
+    /**
+     * Field to order by
+     * Prefix with '-' for descending (e.g., '-publish_date')
+     */
+    orderBy?: string;
+    /**
+     * Maximum records per file
+     * If exceeded, creates paginated files (e.g., contents-1.json, contents-2.json)
+     */
+    limit?: number;
+    /**
+     * Create separate files per unique value of this field
+     * e.g., shardBy: 'year' creates contents-2024.json, contents-2025.json
+     */
+    shardBy?: string;
+}
+
+/**
+ * Filter operators for export queries.
+ *
+ * Used as values in {@link ExportFileConfig.filters} to build SQL `WHERE`
+ * clauses when exporting records to static files.
+ *
+ * @example
+ * ```js
+ * filters: {
+ *   publishDate: { gte: '2025-01-01', lt: '2026-01-01' },
+ *   status: { in: ['published', 'featured'] },
+ * }
+ * ```
+ *
+ * @see {@link ExportFileConfig}
+ */
+export declare interface ExportFilterValue {
+    /** Equals (shorthand: just the value) */
+    eq?: string | number | boolean;
+    /** Not equals */
+    ne?: string | number | boolean;
+    /** Greater than */
+    gt?: string | number;
+    /** Greater than or equal */
+    gte?: string | number;
+    /** Less than */
+    lt?: string | number;
+    /** Less than or equal */
+    lte?: string | number;
+    /** In array */
+    in?: (string | number)[];
+    /** Contains (text) */
+    contains?: string;
+}
+
+/**
+ * Return the full merged configuration synchronously.
+ *
+ * Reads from `globalThis.__smrtConfigCache` without triggering a file search.
+ * Returns `null` when {@link loadConfig} has not been called yet (or after
+ * {@link clearCache} resets the cache).
+ *
+ * @returns The cached {@link SmrtConfig}, or `null` if not yet loaded.
+ *
+ * @example
+ * ```ts
+ * const config = getConfig();
+ * if (config?.smrt?.logLevel === 'debug') {
+ *   console.log('Debug logging enabled');
+ * }
+ * ```
+ *
+ * @see {@link loadConfig}
+ * @see {@link getSiteConfig}
+ * @see {@link getModuleConfig}
+ */
+export declare function getConfig(): SmrtConfig | null;
+
+/**
+ * Return the resolved configuration for a named module.
+ *
+ * Merges four layers in ascending priority order:
+ * 1. `defaults` (caller-supplied fallbacks)
+ * 2. Global `smrt` section of the loaded config
+ * 3. `modules[moduleName]` section of the loaded config
+ * 4. Runtime `modules[moduleName]` overrides set via {@link setConfig}
+ *
+ * Works synchronously — call {@link loadConfig} first to populate the cache.
+ * If no config has been loaded, only `defaults` are returned.
+ *
+ * @param moduleName - Key in `config.modules` (e.g., `'praeco'`).
+ * @param defaults - Optional fallback values used when a key is absent from all
+ *   higher-priority layers.
+ * @returns The fully merged module config typed as `T`.
+ *
+ * @example
+ * ```ts
+ * const config = getModuleConfig('praeco', {
+ *   rssLimit: 50,
+ *   fetchTimeout: 10_000,
+ * });
+ * // config.rssLimit may be overridden by smrt.config.js or setConfig()
+ * ```
+ *
+ * @see {@link getPackageConfig}
+ * @see {@link setConfig}
+ * @see {@link SmrtConfig.modules}
+ */
+export declare function getModuleConfig<T extends Record<string, unknown>>(moduleName: string, defaults?: T): T;
+
+/**
+ * Return the resolved configuration for a named package.
+ *
+ * Identical to {@link getModuleConfig} but reads from `config.packages` instead
+ * of `config.modules`. Use this inside `@happyvertical/smrt-*` packages that
+ * want to expose their own config section without conflicting with user-defined
+ * module names.
+ *
+ * Merges four layers in ascending priority order:
+ * 1. `defaults` (caller-supplied fallbacks)
+ * 2. Global `smrt` section of the loaded config
+ * 3. `packages[packageName]` section of the loaded config
+ * 4. Runtime `packages[packageName]` overrides set via {@link setConfig}
+ *
+ * @param packageName - Key in `config.packages` (e.g., `'ai'`, `'spider'`).
+ * @param defaults - Optional fallback values.
+ * @returns The fully merged package config typed as `T`.
+ *
+ * @example
+ * ```ts
+ * // Inside @happyvertical/smrt-ai package
+ * const config = getPackageConfig('ai', {
+ *   defaultModel: 'gpt-4o-mini',
+ *   maxTokens: 2048,
+ * });
+ * ```
+ *
+ * @see {@link getModuleConfig}
+ * @see {@link setConfig}
+ * @see {@link SmrtConfig.packages}
+ */
+export declare function getPackageConfig<T extends Record<string, unknown>>(packageName: string, defaults?: T): T;
+
+/**
+ * Return the current runtime configuration override store.
+ *
+ * Used internally by {@link getModuleConfig} and {@link getPackageConfig} to
+ * layer runtime overrides on top of file-based config. Prefer those helpers
+ * for reading config; this is a low-level accessor.
+ *
+ * @returns The accumulated runtime config partial.
+ */
+export declare function getRuntimeConfig(): Partial<SmrtConfig>;
+
+/**
+ * Return the `site` section of the loaded configuration.
+ *
+ * Equivalent to `getConfig()?.site ?? null`. Returns `null` both when no
+ * config has been loaded and when the loaded config has no `site` key.
+ *
+ * @returns The {@link SiteConfig} object, or `null` if not defined.
+ *
+ * @example
+ * ```ts
+ * const site = getSiteConfig();
+ * const title = site?.name ?? 'Untitled Site';
+ * ```
+ *
+ * @see {@link SiteConfig}
+ * @see {@link getConfig}
+ */
+export declare function getSiteConfig(): SiteConfig | null;
+
+/**
+ * Load and parse configuration from the project root.
+ *
+ * Searches for `smrt.config.{js,mjs,cjs,json}` starting from the current
+ * working directory and walking up the tree (unless `searchParents: false`).
+ * The result is stored in `globalThis.__smrtConfigCache` so every module in
+ * the process — including pnpm workspace packages loaded from different paths
+ * — sees the same instance.
+ *
+ * Must be called before {@link getConfig}, {@link getModuleConfig}, or
+ * {@link getPackageConfig} return meaningful values (they fall back to an
+ * empty config if called before loading).
+ *
+ * @param options - Optional search path, parent traversal, and cache control.
+ * @returns The parsed {@link SmrtConfig}. Returns `{}` if no file is found.
+ *
+ * @example
+ * ```ts
+ * // Typical app startup
+ * import { loadConfig } from '@happyvertical/smrt-config';
+ * await loadConfig();
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Load a specific file (tests / scripts)
+ * const config = await loadConfig({ configPath: './fixtures/smrt.config.js', cache: false });
+ * ```
+ *
+ * @see {@link getConfig}
+ * @see {@link clearCache}
+ * @see {@link LoadConfigOptions}
+ */
+export declare function loadConfig(options?: LoadConfigOptions): Promise<SmrtConfig>;
+
+/**
+ * Options accepted by {@link loadConfig}.
+ *
+ * All fields are optional; omitting them triggers cosmiconfig's default
+ * search behaviour (scan `cwd` upward for `smrt.config.{js,mjs,cjs,json}`).
+ */
+export declare interface LoadConfigOptions {
+    /**
+     * Absolute or relative path to a specific config file.
+     * When provided, cosmiconfig loads this file directly instead of searching.
+     */
+    configPath?: string;
+    /**
+     * Whether to search parent directories when no config is found in `cwd`.
+     *
+     * @default true
+     */
+    searchParents?: boolean;
+    /**
+     * Whether to cache the loaded config in `globalThis.__smrtLoaderCachedConfig`.
+     * Disable for test isolation or hot-reload scenarios.
+     *
+     * @default true
+     */
+    cache?: boolean;
+}
+
+/**
+ * Merge three config layers in ascending priority order.
+ *
+ * Priority (highest to lowest):
+ * 1. `runtime` — runtime overrides set via {@link setConfig}
+ * 2. `fileConfig` — values loaded from `smrt.config.js`
+ * 3. `defaults` — caller-supplied fallback values
+ *
+ * Uses {@link deepMerge} internally, so `null` / `undefined` source values
+ * never overwrite existing target values.
+ *
+ * @param defaults - Lowest-priority base values (caller defaults).
+ * @param fileConfig - Mid-priority values from the loaded config file.
+ * @param runtime - Highest-priority runtime override values.
+ * @returns A new object with all three layers merged.
+ *
+ * @example
+ * ```ts
+ * const merged = mergeConfigs(
+ *   { timeout: 5000, retries: 3 },
+ *   { retries: 5 },
+ *   { timeout: 1000 },
+ * );
+ * // => { timeout: 1000, retries: 5 }
+ * ```
+ */
+export declare function mergeConfigs<T extends Record<string, unknown>>(defaults: T, fileConfig: Partial<T>, runtime: Partial<T>): T;
+
+/**
+ * Shallow-merge an exported (DB-backed) config into a base (file-backed) config.
+ *
+ * Object values are deep-merged recursively. Primitive values and arrays from
+ * `exportedConfig` replace their counterparts in `baseConfig`. This is a
+ * one-level-smarter spread that lets file-based env overrides win when placed
+ * after the spread.
+ *
+ * Intended for the SSG pattern where an agent exports its runtime config to a
+ * static JSON file and `smrt.config.js` imports it as a base:
+ *
+ * @example
+ * ```js
+ * // smrt.config.js
+ * import exported from './smrt.exported.json' with { type: 'json' };
+ *
+ * export default defineConfig({
+ *   modules: {
+ *     praeco: mergeExportedConfig(exported, {
+ *       apiEndpoint: process.env.API_URL, // env override wins
+ *     }),
+ *   },
+ * });
+ * ```
+ *
+ * @param baseConfig - Lower-priority base (typically from the DB export file).
+ * @param exportedConfig - Higher-priority overrides (typically env / file-based).
+ * @returns A new merged object of type `T`.
+ *
+ * @see {@link exportConfig}
+ * @see {@link parseExportedConfig}
+ */
+export declare function mergeExportedConfig<T extends Record<string, unknown>>(baseConfig: T, exportedConfig: Partial<T>): T;
+
+/**
+ * Database migrations configuration.
+ *
+ * Controls how migrations are generated, stored, and applied. Placed under
+ * the `cli.migrations` key in `smrt.config.js` and consumed by
+ * `@happyvertical/smrt-cli` migration commands (`smrt db:migrate`, etc.).
+ *
+ * @see {@link CliConfig}
+ */
+export declare interface MigrationsConfig {
+    /**
+     * Directory for migration files (relative to project root)
+     *
+     * @default './migrations'
+     */
+    directory?: string;
+    /**
+     * Table name for tracking applied migrations
+     *
+     * @default '_smrt_schema_migrations'
+     */
+    table?: string;
+    /**
+     * Legacy file format setting. File-backed migration generation is not supported.
+     *
+     * @default 'sql'
+     */
+    format?: 'sql' | 'typescript';
+    /**
+     * Migration file naming strategy
+     *
+     * - 'sequence': Sequential numbers (0001, 0002, ...)
+     * - 'timestamp': Unix timestamp-based (20240115143052)
+     *
+     * @default 'sequence'
+     */
+    naming?: 'sequence' | 'timestamp';
+    /**
+     * Migration mode.
+     *
+     * SMRT schema migrations are manifest-driven. File-backed modes are not
+     * supported unless a future file migration executor is implemented.
+     *
+     * @default 'dynamic'
+     */
+    mode?: 'dynamic';
+    /**
+     * Configure mode per environment.
+     *
+     * Overrides the `mode` setting based on NODE_ENV
+     */
+    modeByEnvironment?: {
+        development?: 'dynamic';
+        test?: 'dynamic';
+        staging?: 'dynamic';
+        production?: 'dynamic';
+    };
+    /**
+     * Automatically generate DOWN scripts where safe
+     *
+     * Some operations (DROP COLUMN) may lose data and should be reviewed.
+     *
+     * @default true
+     */
+    autoGenerateDown?: boolean;
+    /**
+     * PostgreSQL-specific settings
+     */
+    postgres?: MigrationsPostgresConfig;
+}
+
+/**
+ * PostgreSQL-specific migration settings.
+ *
+ * Nested under `migrations.postgres` in {@link MigrationsConfig}.
+ */
+export declare interface MigrationsPostgresConfig {
+    /**
+     * Use CREATE INDEX CONCURRENTLY for index creation
+     * Avoids table locks but cannot run in a transaction
+     *
+     * @default true
+     */
+    useConcurrently?: boolean;
+    /**
+     * Lock timeout for migration statements
+     *
+     * @default '30s'
+     */
+    lockTimeout?: string;
+    /**
+     * Statement timeout for migration execution
+     *
+     * @default '60s'
+     */
+    statementTimeout?: string;
+}
+
+/**
+ * Parse a config string previously produced by {@link exportConfig} back into
+ * a plain JavaScript object.
+ *
+ * Handles both output formats:
+ * - **JSON** — standard `JSON.parse`.
+ * - **JS module** — strips the `export default` prefix and trailing semicolon
+ *   before parsing as JSON.
+ *
+ * Throws a `SyntaxError` if the content is not valid JSON after stripping.
+ *
+ * @param content - Exported config string (`'json'` or `'js'` format).
+ * @returns Parsed configuration value.
+ *
+ * @example
+ * ```ts
+ * const raw = await fs.readFile('./smrt.exported.json', 'utf8');
+ * const config = parseExportedConfig(raw);
+ * ```
+ *
+ * @see {@link exportConfig}
+ * @see {@link mergeExportedConfig}
+ */
+export declare function parseExportedConfig(content: string): unknown;
+
+/**
+ * Config export utilities for static site generation
+ *
+ * These utilities enable exporting database-backed agent configurations
+ * to static files for SSG sites.
+ *
+ * @module
+ */
+/**
+ * Deep-clone a config object, removing every key that looks like a secret.
+ *
+ * Keys are tested (case-insensitively, across camelCase / snake_case / kebab /
+ * UPPER variants) against {@link SECRET_PATTERNS}, which cover secrets such as
+ * `apiKey`/`api_key`, `password`, `secret`, `token`, `credential`, `private`,
+ * `auth`/`authorization`/`oauth`, `accessKey`, `signingKey`, `encryptionKey`,
+ * `connectionString`, and `dbUrl`. The policy biases toward over-redaction
+ * because these exports are typically published as static, publicly served
+ * assets — see {@link SECRET_PATTERNS} for the full rationale.
+ *
+ * Nested objects are recursively sanitized; arrays are mapped element-by-element.
+ * `number` / `boolean` primitives pass through unchanged; `string` values are
+ * additionally run through value-level redaction that masks credentials embedded
+ * in a URL (`scheme://user:pass@host` → `scheme://***@host`) as well as
+ * high-confidence secret-token shapes pasted into otherwise-benign keys
+ * (OpenAI/Anthropic `sk-...`, AWS `AKIA...` access key IDs, GitHub/Slack/Google
+ * tokens, `Bearer ...` headers, and PEM private-key blocks) — catching secrets
+ * stored under a benign key the key-based patterns don't match.
+ *
+ * Own `__proto__` / `constructor` / `prototype` keys are dropped to prevent the
+ * cloned result's prototype from being reassigned via the `__proto__` setter.
+ *
+ * This function is called automatically by {@link exportConfig} unless
+ * `includeSecrets: true` is passed.
+ *
+ * @param config - Value to sanitize. Accepts any JSON-serializable structure.
+ * @returns A new value with all secret keys omitted. `null` / `undefined` are
+ *   returned as-is.
+ *
+ * @example
+ * ```ts
+ * const sanitized = sanitizeConfig({
+ *   apiEndpoint: 'https://api.example.com',
+ *   apiKey: 'sk-secret-123',
+ *   nested: { password: 'hunter2', name: 'test' },
+ * });
+ * // => { apiEndpoint: 'https://api.example.com', nested: { name: 'test' } }
+ * ```
+ *
+ * @see {@link exportConfig}
+ */
+export declare function sanitizeConfig(config: unknown): unknown;
+
+/**
+ * Semantic schema contract enforced by SMRT schema commands.
+ *
+ * Object and field requirements are checked against the loaded SMRT registry.
+ * Required fields are also translated to physical table/column checks after
+ * migration/status introspection. `requiredDatabaseShape` is reserved for
+ * database objects that SMRT cannot infer from manifests.
+ */
+export declare interface SchemaContractConfig {
+    requiredObjects?: string[];
+    requiredFields?: string[];
+    requiredDatabaseShape?: {
+        tables?: string[];
+        columns?: string[];
+        indexes?: string[];
+    };
+}
+
+/**
+ * Apply runtime configuration overrides.
+ *
+ * Deep-merges `config` into an in-memory store that takes the highest priority
+ * in every subsequent {@link getModuleConfig} / {@link getPackageConfig} call.
+ * Successive calls accumulate — they do not replace earlier overrides.
+ *
+ * Common uses:
+ * - Inject test doubles or environment-specific values without a config file.
+ * - Apply feature flags from a remote source after startup.
+ *
+ * @param config - Partial {@link SmrtConfig} to merge into the runtime store.
+ *   `null` values are ignored (they do not clear existing keys).
+ *
+ * @example
+ * ```ts
+ * setConfig({ modules: { ai: { defaultModel: 'gpt-4o' } } });
+ * ```
+ *
+ * @see {@link clearCache}
+ * @see {@link getModuleConfig}
+ */
+export declare function setConfig(config: Partial<SmrtConfig>): void;
+
+/**
+ * Site identity and configuration for SMRT site templates.
+ *
+ * Placed under the `site` key in `smrt.config.js`. Retrieved at runtime
+ * via {@link getSiteConfig}. Used by site templates
+ * (`template-sveltekit`, `template-site-static-json`) to define name,
+ * description, navigation, location, and theme.
+ *
+ * @example
+ * ```js
+ * export default defineConfig({
+ *   site: {
+ *     name: 'Bentley Alberta',
+ *     description: 'Community news for Bentley, AB',
+ *     url: 'https://bentley.ca',
+ *     location: { name: 'Bentley', latitude: 52.4, longitude: -113.9, timezone: 'America/Edmonton' },
+ *     navigation: { primary: [{ label: 'Home', href: '/' }] },
+ *   },
+ * });
+ * ```
+ *
+ * @see {@link getSiteConfig}
+ * @see {@link SiteLocation}
+ * @see {@link SiteNavigation}
+ * @see {@link SiteTheme}
+ */
+export declare interface SiteConfig {
+    /** Full site name (e.g., "Bentley Alberta") */
+    name: string;
+    /** Short name for mobile/compact displays */
+    shortName?: string;
+    /** Site description for SEO */
+    description: string;
+    /** Production URL */
+    url?: string;
+    /** Contact email for the site */
+    contactEmail?: string;
+    /** Publisher/organization info */
+    publisher?: SitePublisher;
+    /** Geographic location */
+    location: SiteLocation;
+    /** Navigation structure */
+    navigation: SiteNavigation;
+    /** Theme/branding */
+    theme?: SiteTheme;
+    /** Additional metadata */
+    meta?: {
+        /** Theme color for mobile browsers */
+        themeColor?: string;
+        /** Open Graph locale */
+        ogLocale?: string;
+        /** Google Tag Manager ID */
+        gtmId?: string;
+    };
+}
+
+/**
+ * Geographic location for the site, used for proximity search and display.
+ *
+ * @see {@link SiteConfig}
+ */
+export declare interface SiteLocation {
+    /** Display name (e.g., "Bentley" or "Bentley, AB") */
+    name: string;
+    /** Latitude coordinate */
+    latitude: number;
+    /** Longitude coordinate */
+    longitude: number;
+    /** IANA timezone (e.g., "America/Edmonton") */
+    timezone: string;
+}
+
+/**
+ * Site navigation structure containing primary and optional footer links.
+ *
+ * @see {@link SiteConfig}
+ * @see {@link SiteNavigationLink}
+ */
+export declare interface SiteNavigation {
+    /** Primary navigation links (header) */
+    primary: SiteNavigationLink[];
+    /** Footer navigation links */
+    footer?: SiteNavigationLink[];
+}
+
+/**
+ * A single navigation link item used in site menus.
+ *
+ * @see {@link SiteNavigation}
+ */
+export declare interface SiteNavigationLink {
+    label: string;
+    href: string;
+    icon?: string;
+}
+
+/**
+ * Publisher or organization information displayed in site footers and metadata.
+ *
+ * @see {@link SiteConfig}
+ */
+export declare interface SitePublisher {
+    /** Organization name (e.g., "Blindman Press") */
+    name: string;
+    /** Organization website URL */
+    url?: string;
+    /** GitHub organization URL */
+    github?: string;
+}
+
+/**
+ * Site theme and branding color palette.
+ *
+ * Colors should be provided as CSS hex values (e.g., `'#3b82f6'`).
+ *
+ * @see {@link SiteConfig}
+ */
+export declare interface SiteTheme {
+    /** Primary brand color (hex) */
+    primaryColor: string;
+    /** Light variant of primary color */
+    primaryLight?: string;
+    /** Dark variant of primary color */
+    primaryDark?: string;
+}
+
+/**
+ * Root SMRT configuration structure.
+ *
+ * This is the shape of the object returned by `smrt.config.{js,ts,json}` and
+ * consumed by {@link loadConfig}. Use {@link defineConfig} for type-safe
+ * authoring with IDE auto-completion.
+ *
+ * Priority order (highest to lowest):
+ * 1. Runtime overrides set via {@link setConfig}
+ * 2. File-based config loaded by {@link loadConfig}
+ * 3. Defaults passed to {@link getModuleConfig} / {@link getPackageConfig}
+ *
+ * @example
+ * ```js
+ * // smrt.config.js
+ * import { defineConfig } from '@happyvertical/smrt-config';
+ *
+ * export default defineConfig({
+ *   smrt: { logLevel: 'info', environment: 'production' },
+ *   site: { name: 'My Site', ... },
+ *   modules: { praeco: { rssLimit: 50 } },
+ *   packages: { ai: { defaultModel: 'gpt-4o' } },
+ * });
+ * ```
+ *
+ * @see {@link loadConfig}
+ * @see {@link defineConfig}
+ * @see {@link SmrtGlobalConfig}
+ */
+export declare interface SmrtConfig {
+    /** Global SMRT framework options — lowest-priority base for all modules. */
+    smrt?: SmrtGlobalConfig;
+    /** Site identity and configuration (for site templates). */
+    site?: SiteConfig;
+    /** Export configuration for static site generation. */
+    export?: ExportConfig;
+    /** Domain-scoped agent/developer knowledge generation and exposure. */
+    knowledge?: DomainKnowledgeConfig;
+    /**
+     * Module-scoped configurations keyed by module name.
+     * Retrieved via {@link getModuleConfig}.
+     */
+    modules?: {
+        [moduleName: string]: Record<string, unknown>;
+    };
+    /**
+     * Package-scoped configurations keyed by package name.
+     * Retrieved via {@link getPackageConfig}.
+     */
+    packages?: {
+        [packageName: string]: Record<string, unknown>;
+    };
+}
+
+/**
+ * Global SMRT framework options that apply to all modules unless overridden.
+ *
+ * Placed under the `smrt` key in `smrt.config.js`. Values here propagate
+ * as the lowest-priority base for every `getModuleConfig()` and
+ * `getPackageConfig()` call.
+ *
+ * @example
+ * ```js
+ * // smrt.config.js
+ * export default defineConfig({
+ *   smrt: {
+ *     logLevel: 'debug',
+ *     environment: 'development',
+ *     embeddings: { provider: 'local' },
+ *   },
+ * });
+ * ```
+ *
+ * @see {@link SmrtConfig}
+ * @see {@link getModuleConfig}
+ * @see {@link getPackageConfig}
+ */
+export declare interface SmrtGlobalConfig {
+    cacheDir?: string;
+    logLevel?: 'debug' | 'info' | 'warn' | 'error';
+    environment?: 'development' | 'production' | 'test';
+    /**
+     * Schema migration strategy when parent class schema changes
+     *
+     * Options:
+     * - 'warn': Log warning about schema mismatch, require manual migration (safest)
+     * - 'auto-add': Automatically ALTER TABLE to add new parent fields (default, convenient)
+     *
+     * Note: Removing columns is never automatic - always requires manual migration
+     *
+     * @default 'auto-add'
+     */
+    schemaMigration?: {
+        strategy?: 'warn' | 'auto-add';
+    };
+    /**
+     * Inheritance configuration
+     */
+    inheritance?: {
+        /**
+         * Behavior when an ancestor class is missing from the registry
+         *
+         * Options:
+         * - 'error': Throw an error (strict, catches bugs)
+         * - 'warn': Log warning and skip (lenient, default)
+         *
+         * @default 'warn'
+         */
+        onMissingAncestor?: 'error' | 'warn';
+        /**
+         * Size of LRU cache for inheritance chains and merged fields
+         *
+         * Higher values improve performance but use more memory.
+         * Each entry stores one inheritance chain (array of strings).
+         *
+         * @default 200
+         */
+        cacheSize?: number;
+    };
+    /**
+     * Embedding configuration for semantic search
+     *
+     * Project-level settings that apply to all SMRT objects
+     * unless overridden in the @smrt() decorator.
+     */
+    embeddings?: {
+        /**
+         * Standard dimensions for embeddings in this project
+         *
+         * All embeddings should use the same dimensions for consistency.
+         * Common values: 384, 768, 1536
+         *
+         * @default 768
+         */
+        dimensions?: number;
+        /**
+         * Embedding provider type
+         *
+         * - 'local': Use local Node.js model (@xenova/transformers)
+         * - 'ai': Use AI library (OpenAI, etc.)
+         * - 'auto': Try local first, fallback to AI
+         *
+         * @default 'local'
+         */
+        provider?: 'local' | 'ai' | 'auto';
+        /**
+         * Local model to use (when provider is 'local' or 'auto')
+         *
+         * Hugging Face model ID for @xenova/transformers.
+         * Model is downloaded on first use (~440MB for bge-base-en-v1.5).
+         *
+         * @default 'Xenova/bge-base-en-v1.5'
+         */
+        localModel?: string;
+        /**
+         * AI model to use (when provider is 'ai' or fallback)
+         *
+         * OpenAI embedding model name.
+         *
+         * @default 'text-embedding-3-small'
+         */
+        aiModel?: string;
+        /**
+         * Whether to fallback to AI if local embedding fails
+         *
+         * Only applies when provider is 'auto'.
+         *
+         * @default true
+         */
+        fallbackToAI?: boolean;
+        /**
+         * Storage mode for embeddings
+         *
+         * - 'json': Store as JSON text, in-memory similarity (works everywhere)
+         * - 'native': Use database vector operations when available, fallback to json
+         *
+         * @default 'json'
+         */
+        storage?: 'json' | 'native';
+    };
+    [key: string]: unknown;
+}
+
+export { }