@happyvertical/smrt-config 0.30.0

package/AGENTS.md

@@ -0,0 +1,35 @@
+# @happyvertical/smrt-config
+
+Configuration management with cosmiconfig, secret sanitization, and SSG export.
+
+## How It Works
+
+1. **cosmiconfig loader** searches for `smrt.config.{js,ts,json}` (via `loadConfig()`)
+2. **Priority**: runtime (highest) > file config > defaults
+3. **globalThis caching**: `globalThis.__smrtConfigCache` — all modules share one config instance
+
+## Key Functions
+
+| Function | Purpose |
+|----------|---------|
+| `loadConfig()` | Async load from file (cosmiconfig) |
+| `getConfig()` | Get full merged config |
+| `getModuleConfig(name)` | Module-scoped config section |
+| `getPackageConfig(name)` | Package-scoped config section |
+| `setConfig(overrides)` | Runtime overrides (highest priority) |
+| `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 |
+
+## 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/types.ts` — full config schema (~800 lines)
+
+## Gotchas
+
+- **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

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# @happyvertical/smrt-config
+
+Centralized configuration management for the SMRT framework. Uses [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig) to load `smrt.config.{js,ts,json}` files, with secret sanitization and SSG-safe export.
+
+## Installation
+
+```bash
+pnpm add @happyvertical/smrt-config
+```
+
+## Usage
+
+### Create a config file
+
+```javascript
+// smrt.config.js
+export default {
+  smrt: {
+    cacheDir: '.cache',
+    logLevel: 'info',
+  },
+
+  packages: {
+    ai: {
+      defaultProvider: 'anthropic',
+      defaultModel: 'claude-sonnet-4-20250514',
+      apiKeys: {
+        anthropic: process.env.ANTHROPIC_API_KEY,
+      },
+    },
+  },
+
+  modules: {
+    'town-scraper': {
+      cronSchedule: '0 0 * * *',
+      maxPages: 100,
+    },
+  },
+};
+```
+
+### Use config in code
+
+```typescript
+import { loadConfig, getPackageConfig, getModuleConfig, setConfig } from '@happyvertical/smrt-config';
+
+// Load config from file (cosmiconfig auto-discovery)
+await loadConfig();
+
+// Get package-scoped config with defaults
+const aiConfig = getPackageConfig('ai', {
+  defaultProvider: 'openai',
+  defaultModel: 'gpt-4',
+});
+
+// Get module-scoped config with defaults
+const scraperConfig = getModuleConfig('town-scraper', {
+  cronSchedule: '0 0 * * *',
+  maxPages: 50,
+});
+
+// Runtime overrides (highest priority)
+setConfig({
+  packages: {
+    ai: { defaultModel: 'gpt-4-turbo' },
+  },
+});
+```
+
+### Type-safe config files
+
+```typescript
+import { defineConfig } from '@happyvertical/smrt-config';
+
+export default defineConfig({
+  smrt: {
+    logLevel: 'info',
+  },
+  packages: {
+    ai: {
+      defaultProvider: 'anthropic',
+    },
+  },
+});
+```
+
+### SSG-safe export
+
+```typescript
+import { loadConfig, exportConfig, sanitizeConfig } from '@happyvertical/smrt-config';
+
+const config = await loadConfig();
+
+// Export config without secrets (safe for static site generation)
+const safeJson = exportConfig(config, { includeSecrets: false });
+
+// Or manually sanitize — strips secret-bearing keys (case-insensitive, across
+// camelCase / snake_case / kebab / UPPER variants): apiKey, password, secret,
+// token, credential, private, oauth, authorization, accessKey, signingKey, encryptionKey,
+// connectionString, dbUrl, cookie, salt, cert, and similar. Biases toward
+// over-redaction; pass `{ includeSecrets: true }` to opt out.
+const sanitized = sanitizeConfig(config);
+```
+
+## API
+
+### Functions
+
+| Export | Description |
+|--------|------------|
+| `loadConfig(options?)` | Async load from file via cosmiconfig |
+| `getConfig()` | Get full merged config |
+| `getPackageConfig(name, defaults?)` | Get package-scoped config section |
+| `getModuleConfig(name, defaults?)` | Get module-scoped config section |
+| `getSiteConfig()` | Get site-level config |
+| `setConfig(overrides)` | Runtime overrides (highest priority) |
+| `clearCache()` | Reset cached config (global — affects all modules) |
+| `defineConfig(config)` | Type-safe config file helper |
+| `exportConfig(config, options?)` | SSG-safe export (defaults to no secrets) |
+| `sanitizeConfig(config)` | Strip secret-matching keys |
+| `mergeExportedConfig(baseConfig, exportedConfig)` | Merge an exported config over a base |
+| `parseExportedConfig(raw)` | Parse an exported config string |
+
+### Priority Order
+
+Configuration merging (highest to lowest):
+
+1. Runtime overrides via `setConfig()`
+2. Config file (`smrt.config.{js,ts,json}`)
+3. Package/module defaults
+
+### Key Types
+
+`SmrtConfig`, `SmrtGlobalConfig`, `DatabaseConfig`, `SiteConfig`, `MigrationsConfig`, `LoadConfigOptions`, `ExportConfig`, `ExportConfigOptions`
+
+## Dependencies
+
+No sibling package dependencies. This is a foundation-layer package.