@happyvertical/smrt-config 0.55.3 → 0.55.5

package/dist/shared.d.ts

@@ -0,0 +1,277 @@
+import { type ResolveAIProviderOptions, type ResolvedAIProviderConfig } from './ai.js';
+import { type ResolvedCliDatabase } from './database-environment.js';
+import { type ResolvedApplicationRuntime } from './runtime-profile.js';
+import type { AIConfigBlock, SmrtConfig } from './types.js';
+export { AI_PROVIDER_KEY_ENV, type AIConfigField, type AIConfigSource, type AIExplicitConfig, type AIProviderClientOptions, AIProviderNotConfiguredError, canonicalizeAIConfig, DEFAULT_AI_ENV_PREFIXES, describeAIProviderConfig, getDefaultAIKeyEnvName, mergeAIConfigObjects, type ResolveAIProviderOptions, type ResolvedAIProviderConfig, redactBaseUrl, resolveAIProviderConfig, toAIClientOptions, tryResolveAIProviderConfig, withAIAliases, } from './ai.js';
+export type { CliDatabaseSource, CliDatabaseType, ResolvedCliDatabase, } from './database-environment.js';
+export { type ExportConfigOptions, exportConfig, mergeExportedConfig, parseExportedConfig, sanitizeConfig, } from './export.js';
+export { clearRuntimeConfig, getRuntimeConfig, mergeConfigs } from './merge.js';
+export type { ApplicationRuntimeConfig, ApplicationRuntimeProfile, AssetOwnership, AssetStorageProvider, AuthenticationProvider, BackupProvider, ConnectionOwnership, DatabaseEngine, JobTopology, NetworkExposure, OwnerBootstrapMode, ResolvedApplicationRuntime, RuntimeAssetProvider, RuntimeAuthenticationProvider, RuntimeCapabilities, RuntimeDatabaseProvider, RuntimeInvariants, RuntimeJobProvider, RuntimeNetworkProvider, RuntimeOverrideReport, RuntimePortabilityProvider, RuntimeProfileValidationIssue, RuntimeProviderOverrides, RuntimeProviders, RuntimeSecretProvider, RuntimeTenancyProvider, SecretOwnership, SecretProvider, TenancyMode, TenantContextMode, TenantIsolation, } from './runtime-profile.js';
+export { getApplicationRuntimePreset, RuntimeProfileValidationError, resolveApplicationRuntime, } from './runtime-profile.js';
+export type { AIConfigBlock, CliConfig, DatabaseConfig, ExportConfig, ExportFileConfig, ExportFilterValue, LoadConfigOptions, MigrationsConfig, MigrationsPostgresConfig, PostgresPermissionsConfig, SchemaContractConfig, SiteConfig, SiteLocation, SiteNavigation, SiteNavigationLink, SitePublisher, SiteTheme, SmrtConfig, SmrtGlobalConfig, } from './types.js';
+/**
+ * Return the loaded file 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 resolveConfiguredApplicationRuntime}
+ * @see {@link getSiteConfig}
+ * @see {@link getModuleConfig}
+ */
+export declare function getConfig(): SmrtConfig | null;
+/**
+ * Resolve the effective application runtime using the documented config
+ * priority: runtime overrides set by {@link setConfig} > loaded file config >
+ * profile defaults.
+ *
+ * This accessor is intentionally separate from {@link getConfig}, whose legacy
+ * contract returns the loaded file object only. When a runtime override selects
+ * a different profile, lower-priority provider overrides are discarded so they
+ * cannot leak profile-specific choices (for example local files or inline jobs)
+ * into the new profile. Provider overrides still deep-merge when the profile is
+ * unchanged.
+ *
+ * @returns A validated, deterministic, secret-free runtime snapshot.
+ * @throws {RuntimeProfileValidationError} When no profile is configured or the
+ * effective provider composition violates a profile invariant.
+ */
+export declare function resolveConfiguredApplicationRuntime(): Readonly<ResolvedApplicationRuntime>;
+/**
+ * Resolve the runtime an application actually runs with, from its loaded
+ * file config plus {@link setConfig} runtime overrides.
+ *
+ * The one rule `smrt app` and the SvelteKit runtime share (#3446): when
+ * neither layer declares a `runtime` block — the property is absent, or
+ * explicitly `undefined` — the application runs the `local` profile.
+ * Otherwise this is {@link resolveConfiguredApplicationRuntime}, so a present
+ * value that is not a runtime block (`null`, `false`, `0`, `''`, a string, an
+ * array) fails closed with the same {@link RuntimeProfileValidationError}
+ * instead of silently selecting `local`.
+ *
+ * @param config - The file configuration returned by {@link loadConfig};
+ * `null`/`undefined` means no file configuration.
+ * @returns A validated, deterministic, secret-free runtime snapshot.
+ * @throws {RuntimeProfileValidationError} When a declared runtime block is not
+ * an object or violates a profile invariant.
+ *
+ * @example
+ * ```ts
+ * const runtime = resolveEffectiveApplicationRuntime(await loadConfig());
+ * ```
+ */
+export declare function resolveEffectiveApplicationRuntime(config: SmrtConfig | null | undefined): Readonly<ResolvedApplicationRuntime>;
+/**
+ * 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(): import('./types.js').SiteConfig | 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;
+/**
+ * Resolve the database `smrt` commands and `smrt-dev-mcp` use: the declared
+ * `packages.cli.database` from any config layer, else `DATABASE_URL` /
+ * `DATABASE_TYPE` (#3410, #3446).
+ *
+ * A configured `database.url` always wins and the environment is not read.
+ * Otherwise `DATABASE_URL` supplies the URL and its engine comes from the
+ * config's `database.type`, else `DATABASE_TYPE`, else the URL scheme. An
+ * unsupported `DATABASE_TYPE` yields `invalid-environment` instead of a guess.
+ * Read-only: nothing is written to the config. Call after {@link loadConfig}.
+ *
+ * @param env - Environment to read (defaults to `process.env`).
+ * @returns The source and, for `config`/`environment`, the database block.
+ *
+ * @example
+ * ```ts
+ * await loadConfig();
+ * const { source, database } = resolveCliDatabaseConfig();
+ * ```
+ */
+export declare function resolveCliDatabaseConfig(env?: Readonly<Record<string, string | undefined>>): ResolvedCliDatabase;
+/**
+ * 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;
+/**
+ * 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. When a call explicitly changes the runtime
+ * profile, the stored runtime provider subtree is reset before merging so
+ * profile-specific selectors cannot leak into the new profile.
+ *
+ * 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;
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * The effective `ai` block: runtime `ai` > runtime `packages.ai` > file `ai` >
+ * file `packages.ai` (`smrt init` historically wrote `packages.ai`), merged
+ * field by field. Returns `null` when none is declared.
+ */
+export declare function getAIConfigBlock(): AIConfigBlock | null;
+/**
+ * Merge `ai` block layers, lowest priority first, preserving provider
+ * ownership: `apiKey`, `apiKeyEnv`, `baseUrl` and `model` belong to the
+ * provider their layer names. When a higher layer names a different provider,
+ * the credentials and model already collected from lower layers for another
+ * provider are dropped (a model id is provider-specific, so it is dropped
+ * too). A layer that names no provider contributes generic values that bind to
+ * the provider selected so far.
+ */
+export declare function mergeAIConfigLayers(layers: ReadonlyArray<unknown>): AIConfigBlock | null;
+/**
+ * {@link resolveAIProviderConfig} against the loaded `smrt.config.ts` `ai`
+ * block. Throws `AIProviderNotConfiguredError` when nothing is configured.
+ */
+export declare function resolveConfiguredAIProvider(options?: ResolveAIProviderOptions): ResolvedAIProviderConfig;
+/** Non-throwing variant of {@link resolveConfiguredAIProvider}. */
+export declare function tryResolveConfiguredAIProvider(options?: ResolveAIProviderOptions): ResolvedAIProviderConfig | undefined;
+//# sourceMappingURL=shared.d.ts.map

package/dist/shared.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-config",
-  "version": "0.55.3",
+  "version": "0.55.5",
   "type": "module",
   "description": "Centralized configuration management for SMRT modules",
   "author": "HappyVertical",
@@ -10,6 +10,7 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "browser": "./dist/browser.js",
       "import": "./dist/index.js"
     }
   },
@@ -19,7 +20,7 @@
     "AGENTS.md"
   ],
   "dependencies": {
-    "@happyvertical/smrt-types": "0.55.3",
+    "@happyvertical/smrt-types": "0.55.5",
     "cosmiconfig": "^10.0.1",
     "jiti": "^2.7.0"
   },