@happyvertical/smrt-config 0.43.5 → 0.43.7

package/AGENTS.md

@@ -20,12 +20,16 @@ Configuration management with cosmiconfig, secret sanitization, and SSG export.
 | `clearCache()` | Reset cached config — affects all modules |
 | `exportConfig({ includeSecrets })` | SSG-safe export (defaults to no secrets) |
 | `sanitizeConfig(config)` | Strips keys matching: apiKey, password, secret, token, credential, private, auth, key |
+| `resolveApplicationRuntime(config)` | Resolve and validate a local, self-hosted, or cloud infrastructure profile |
+| `resolveConfiguredApplicationRuntime()` | Resolve loaded file config plus highest-priority `setConfig()` runtime overrides |
+| `getApplicationRuntimePreset(profile)` | Inspect a profile's safe provider defaults |
 
 ## Key Files
 
 - `src/loader.ts` — cosmiconfig integration and file discovery
 - `src/merge.ts` — deep merge logic, runtime config store
 - `src/export.ts` — sanitization and export formatting (JSON/JS)
+- `src/runtime-profile.ts` — application runtime presets, validation, capabilities, and diagnostics
 - `src/types.ts` — full config schema (~800 lines)
 
 ## Gotchas
@@ -33,3 +37,5 @@ Configuration management with cosmiconfig, secret sanitization, and SSG export.
 - **clearCache() is global**: affects all modules sharing the config instance
 - **SSG export defaults to no secrets**: must explicitly set `includeSecrets: true` to include them
 - **Deep merge**: later values override earlier ones at each key level
+- **Profiles do not alter application policy**: domain objects, generated REST/CLI/MCP/WebMCP surfaces, action effects, approval policy, authorization records, and job invocation stay identical across profiles.
+- **Runtime snapshots contain selectors, never credentials**: provider-specific URLs, tokens, paths, and secret values belong in the implementing provider's configuration. Unknown runtime fields fail closed.

package/README.md

@@ -15,6 +15,10 @@ pnpm add @happyvertical/smrt-config
 ```javascript
 // smrt.config.js
 export default {
+  runtime: {
+    profile: 'local',
+  },
+
   smrt: {
     cacheDir: '.cache',
     logLevel: 'info',
@@ -39,6 +43,69 @@ export default {
 };
 ```
 
+### Application runtime profiles
+
+`runtime.profile` selects a validated infrastructure composition without
+forking application objects or workflows. Validation happens before startup;
+unsupported combinations throw `RuntimeProfileValidationError` with a recovery
+action.
+
+```typescript
+// smrt.config.ts
+import { defineConfig } from '@happyvertical/smrt-config';
+
+export default defineConfig({
+  runtime: {
+    profile: 'self-hosted',
+    providers: {
+      authentication: { provider: 'magic-link' },
+      tenancy: { mode: 'multi-tenant', context: 'required' },
+      assets: { provider: 'local-files' },
+    },
+  },
+});
+```
+
+```typescript
+// application startup
+import {
+  loadConfig,
+  resolveConfiguredApplicationRuntime,
+} from '@happyvertical/smrt-config';
+
+await loadConfig();
+const runtime = resolveConfiguredApplicationRuntime();
+// Safe for doctor output and agent inspection: provider selectors and derived
+// capabilities are present; URLs, paths, credentials, and secret values are not.
+console.log(JSON.stringify(runtime));
+```
+
+| Profile | Database | Authentication | Tenancy | Assets / secrets | Jobs | Network |
+| --- | --- | --- | --- | --- | --- | --- |
+| `local` | user-owned SQLite | single-use owner bootstrap | real default tenant | user-owned local files | embedded (`inline` override allowed) | loopback |
+| `self-hosted` | operator PostgreSQL | OIDC (`magic-link` allowed) | single tenant (`multi-tenant` allowed) | S3-compatible + environment secrets (documented local/external overrides allowed) | external worker | public TLS |
+| `cloud` | managed PostgreSQL | hosted identity | required multi-tenant context, application isolation or RLS | managed object storage/secrets | scalable workers | public TLS |
+
+Every profile supports logical export/import. The local profile additionally
+advertises file-snapshot backup; deployment profiles assign physical backup to
+the operator or managed provider.
+
+The override seam selects only infrastructure providers. It cannot modify
+domain models, generated REST/CLI/MCP/WebMCP definitions, action-effect
+metadata, approval policy, authorization records, or the job invocation API.
+Those are cross-profile invariants and are emitted in every resolved snapshot.
+Provider implementations keep their credentials and connection values in their
+own configuration; do not add those values to `runtime.providers`.
+
+Use `resolveApplicationRuntime(config.runtime)` for a pure, explicit value such
+as a test fixture. Application startup should use
+`resolveConfiguredApplicationRuntime()`: it composes the loaded file with
+highest-priority `setConfig()` overrides before validation. `getConfig()` keeps
+its legacy meaning and returns only loaded file state. Successive `setConfig()`
+calls deep-merge providers while the profile is unchanged; an explicit profile
+switch resets earlier runtime provider selections before applying the new
+profile.
+
 ### Use config in code
 
 ```typescript
@@ -118,6 +185,9 @@ const sanitized = sanitizeConfig(config);
 | `defineConfig(config)` | Type-safe config file helper |
 | `exportConfig(config, options?)` | SSG-safe export (defaults to no secrets) |
 | `sanitizeConfig(config)` | Strip secret-matching keys |
+| `resolveApplicationRuntime(config)` | Resolve and fail-closed validate a runtime profile |
+| `resolveConfiguredApplicationRuntime()` | Resolve effective file plus runtime-overridden profile config |
+| `getApplicationRuntimePreset(profile)` | Inspect an immutable copy of a profile preset |
 | `mergeExportedConfig(baseConfig, exportedConfig)` | Merge an exported config over a base |
 | `parseExportedConfig(raw)` | Parse an exported config string |
 
@@ -131,7 +201,7 @@ Configuration merging (highest to lowest):
 
 ### Key Types
 
-`SmrtConfig`, `SmrtGlobalConfig`, `DatabaseConfig`, `SiteConfig`, `MigrationsConfig`, `LoadConfigOptions`, `ExportConfig`, `ExportConfigOptions`
+`SmrtConfig`, `SmrtGlobalConfig`, `ApplicationRuntimeConfig`, `ResolvedApplicationRuntime`, `RuntimeProviders`, `RuntimeCapabilities`, `RuntimeInvariants`, `RuntimeProfileValidationError`, `DatabaseConfig`, `SiteConfig`, `MigrationsConfig`, `LoadConfigOptions`, `ExportConfig`, `ExportConfigOptions`
 
 ## Dependencies
 

package/dist/index.d.ts

@@ -1,5 +1,28 @@
 import { DomainKnowledgeConfig } from '@happyvertical/smrt-types';
 
+/** Canonical config stored at `runtime` in `smrt.config.ts`. */
+export declare interface ApplicationRuntimeConfig {
+    profile: ApplicationRuntimeProfile;
+    providers?: RuntimeProviderOverrides;
+}
+
+/**
+ * Stable application-runtime profile contract.
+ *
+ * Profiles select infrastructure composition only. Domain models, generated
+ * surfaces, effect metadata, and approval policy are deliberately outside the
+ * override surface so moving an application cannot silently change behavior.
+ */
+export declare type ApplicationRuntimeProfile = 'local' | 'self-hosted' | 'cloud';
+
+export declare type AssetOwnership = 'user' | 'operator' | 'managed';
+
+export declare type AssetStorageProvider = 'local-files' | 's3-compatible' | 'managed-object-storage';
+
+export declare type AuthenticationProvider = 'owner-bootstrap' | 'oidc' | 'magic-link' | 'hosted-identity';
+
+export declare type BackupProvider = 'file-snapshot' | 'operator' | 'managed';
+
 /**
  * Reset all cached configuration state.
  *
@@ -71,6 +94,8 @@ export declare interface CliConfig {
     schemaContract?: SchemaContractConfig;
 }
 
+export declare type ConnectionOwnership = 'user' | 'operator' | 'managed';
+
 /**
  * Database connection configuration for CLI commands.
  *
@@ -95,6 +120,8 @@ export declare interface DatabaseConfig {
     url?: string;
 }
 
+export declare type DatabaseEngine = 'sqlite' | 'postgres';
+
 /**
  * Type-safe helper for authoring `smrt.config.js` files.
  *
@@ -327,8 +354,11 @@ export declare interface ExportFilterValue {
     contains?: string;
 }
 
+/** Return a fresh copy of the documented preset for inspection and tooling. */
+export declare function getApplicationRuntimePreset(profile: ApplicationRuntimeProfile): Readonly<RuntimeProviders>;
+
 /**
- * Return the full merged configuration synchronously.
+ * 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
@@ -345,6 +375,7 @@ export declare interface ExportFilterValue {
  * ```
  *
  * @see {@link loadConfig}
+ * @see {@link resolveConfiguredApplicationRuntime}
  * @see {@link getSiteConfig}
  * @see {@link getModuleConfig}
  */
@@ -445,6 +476,8 @@ export declare function getRuntimeConfig(): Partial<SmrtConfig>;
  */
 export declare function getSiteConfig(): SiteConfig | null;
 
+export declare type JobTopology = 'inline' | 'embedded' | 'external' | 'scalable';
+
 /**
  * Load and parse configuration from the project root.
  *
@@ -684,6 +717,10 @@ export declare interface MigrationsPostgresConfig {
     statementTimeout?: string;
 }
 
+export declare type NetworkExposure = 'loopback' | 'public';
+
+export declare type OwnerBootstrapMode = 'single-use' | 'disabled';
+
 /**
  * Parse a config string previously produced by {@link exportConfig} back into
  * a plain JavaScript object.
@@ -709,6 +746,166 @@ export declare interface MigrationsPostgresConfig {
  */
 export declare function parseExportedConfig(content: string): unknown;
 
+/**
+ * Resolve a safe preset and explicit provider overrides into a stable snapshot.
+ *
+ * The resolver is pure: it reads no environment variables, paths, credentials,
+ * clocks, or process state. Invalid and unknown fields fail before startup.
+ */
+export declare function resolveApplicationRuntime(config: ApplicationRuntimeConfig): Readonly<ResolvedApplicationRuntime>;
+
+/**
+ * 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>;
+
+/** Deterministic, secret-free runtime diagnostic snapshot. */
+export declare interface ResolvedApplicationRuntime {
+    readonly schemaVersion: 1;
+    readonly profile: ApplicationRuntimeProfile;
+    readonly providers: RuntimeProviders;
+    readonly capabilities: RuntimeCapabilities;
+    readonly invariants: RuntimeInvariants;
+    readonly diagnostics: {
+        readonly secretValuesIncluded: false;
+        readonly overrides: readonly RuntimeOverrideReport[];
+        readonly unsafeOverrides: readonly [];
+    };
+}
+
+export declare interface RuntimeAssetProvider {
+    readonly provider: AssetStorageProvider;
+    readonly ownership: AssetOwnership;
+}
+
+export declare interface RuntimeAuthenticationProvider {
+    readonly provider: AuthenticationProvider;
+    readonly ownerBootstrap: OwnerBootstrapMode;
+}
+
+/** Derived capabilities used by startup, doctor, tests, and agent inspection. */
+export declare interface RuntimeCapabilities {
+    readonly ownerBootstrap: boolean;
+    readonly publicAuthentication: boolean;
+    readonly defaultTenant: boolean;
+    readonly multiTenant: boolean;
+    readonly localAssets: boolean;
+    readonly externalWorkers: boolean;
+    readonly backup: true;
+    readonly logicalExport: true;
+    readonly logicalImport: true;
+    readonly diagnostics: true;
+    readonly orchestrationHealth: boolean;
+}
+
+export declare interface RuntimeDatabaseProvider {
+    readonly engine: DatabaseEngine;
+    readonly connectionOwnership: ConnectionOwnership;
+}
+
+/** Behaviors that provider/profile selection is never allowed to change. */
+export declare interface RuntimeInvariants {
+    readonly domainModels: 'identical';
+    readonly generatedRest: 'identical';
+    readonly generatedCli: 'identical';
+    readonly generatedMcp: 'identical';
+    readonly generatedWebMcp: 'identical';
+    readonly mcpExposurePolicy: 'identical';
+    readonly webMcpExposurePolicy: 'identical';
+    readonly actionEffects: 'identical';
+    readonly approvalPolicy: 'identical';
+    readonly authorizationRecords: 'required';
+    readonly jobInvocation: 'identical';
+    readonly portability: 'logical-export-import';
+}
+
+export declare interface RuntimeJobProvider {
+    readonly topology: JobTopology;
+}
+
+export declare interface RuntimeNetworkProvider {
+    readonly exposure: NetworkExposure;
+    readonly tls: boolean;
+}
+
+export declare interface RuntimeOverrideReport {
+    readonly path: string;
+    readonly from: string | boolean;
+    readonly to: string | boolean;
+}
+
+export declare interface RuntimePortabilityProvider {
+    readonly backup: BackupProvider;
+    readonly logicalExport: true;
+    readonly logicalImport: true;
+}
+
+/** Aggregates deterministic, actionable failures before application startup. */
+export declare class RuntimeProfileValidationError extends Error {
+    readonly issues: readonly RuntimeProfileValidationIssue[];
+    constructor(issues: RuntimeProfileValidationIssue[]);
+}
+
+export declare interface RuntimeProfileValidationIssue {
+    code: 'invalid_config' | 'unsupported_field' | 'incompatible_provider';
+    path: string;
+    message: string;
+    recovery: string;
+}
+
+/**
+ * Explicit provider changes layered over a profile's safe preset.
+ *
+ * Every override is revalidated with the completed composition. Capability and
+ * surface-policy fields are intentionally absent: providers cannot use this
+ * seam to weaken cross-profile invariants.
+ */
+export declare interface RuntimeProviderOverrides {
+    database?: Partial<RuntimeDatabaseProvider>;
+    authentication?: Partial<RuntimeAuthenticationProvider>;
+    tenancy?: Partial<RuntimeTenancyProvider>;
+    assets?: Partial<RuntimeAssetProvider>;
+    secrets?: Partial<RuntimeSecretProvider>;
+    jobs?: Partial<RuntimeJobProvider>;
+    network?: Partial<RuntimeNetworkProvider>;
+}
+
+/** Fully selected infrastructure providers for an application runtime. */
+export declare interface RuntimeProviders {
+    readonly database: RuntimeDatabaseProvider;
+    readonly authentication: RuntimeAuthenticationProvider;
+    readonly tenancy: RuntimeTenancyProvider;
+    readonly assets: RuntimeAssetProvider;
+    readonly secrets: RuntimeSecretProvider;
+    readonly jobs: RuntimeJobProvider;
+    readonly network: RuntimeNetworkProvider;
+    readonly portability: RuntimePortabilityProvider;
+}
+
+export declare interface RuntimeSecretProvider {
+    readonly provider: SecretProvider;
+    readonly ownership: SecretOwnership;
+}
+
+export declare interface RuntimeTenancyProvider {
+    readonly mode: TenancyMode;
+    readonly context: TenantContextMode;
+    readonly isolation: TenantIsolation;
+}
+
 /**
  * Config export utilities for static site generation
  *
@@ -779,12 +976,18 @@ export declare interface SchemaContractConfig {
     };
 }
 
+export declare type SecretOwnership = 'user' | 'operator' | 'managed';
+
+export declare type SecretProvider = 'local-file' | 'environment' | 'external' | 'managed';
+
 /**
  * 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.
+ * 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.
@@ -967,6 +1170,8 @@ export declare interface SmrtConfig {
     export?: ExportConfig;
     /** Domain-scoped agent/developer knowledge generation and exposure. */
     knowledge?: DomainKnowledgeConfig;
+    /** Validated application infrastructure composition. */
+    runtime?: ApplicationRuntimeConfig;
     /**
      * Module-scoped configurations keyed by module name.
      * Retrieved via {@link getModuleConfig}.
@@ -1112,4 +1317,10 @@ export declare interface SmrtGlobalConfig {
     [key: string]: unknown;
 }
 
+export declare type TenancyMode = 'default-tenant' | 'single-tenant' | 'multi-tenant';
+
+export declare type TenantContextMode = 'defaulted' | 'required';
+
+export declare type TenantIsolation = 'application' | 'database-rls';
+
 export { }