@push.rocks/smartconfig 6.0.1 → 6.1.0

package/.smartconfig.json

@@ -1,14 +1,10 @@
 {
-  "npmci": {
-    "globalNpmTools": [],
-    "npmAccessLevel": "public"
-  },
   "npmts": {
     "testConfig": {
       "parallel": false
     }
   },
-  "gitzone": {
+  "@git.zone/cli": {
     "projectType": "npm",
     "module": {
       "githost": "code.foss.global",
@@ -34,9 +30,19 @@
         "workflow improvement",
         "persistent storage"
       ]
+    },
+    "release": {
+      "registries": [
+        "https://verdaccio.lossless.digital",
+        "https://registry.npmjs.org"
+      ],
+      "accessLevel": "public"
     }
   },
-  "tsdoc": {
+  "@git.zone/tsdoc": {
     "legal": "\n## License and Legal Information\n\nThis repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. \n\n**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.\n\n### Trademarks\n\nThis project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.\n\n### Company Information\n\nTask Venture Capital GmbH  \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.\n"
+  },
+  "@ship.zone/szci": {
+    "globalNpmTools": []
   }
-}
+}

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@push.rocks/smartconfig',
-    version: '6.0.1',
+    version: '6.1.0',
     description: 'A comprehensive configuration management library providing key-value storage, environment variable mapping, and tool configuration.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx5QkFBeUI7SUFDL0IsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLHFJQUFxSTtDQUNuSixDQUFBIn0=

package/license

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Task Venture Capital GmbH
+
+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/package.json

@@ -1,10 +1,15 @@
 {
   "name": "@push.rocks/smartconfig",
-  "version": "6.0.1",
+  "version": "6.1.0",
   "private": false,
   "description": "A comprehensive configuration management library providing key-value storage, environment variable mapping, and tool configuration.",
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",
+  "scripts": {
+    "test": "(tstest test/ --verbose --logfile --timeout 20)",
+    "build": "(tsbuild --web --allowimplicitany)",
+    "buildDocs": "tsdoc"
+  },
   "repository": {
     "type": "git",
     "url": "https://code.foss.global/push.rocks/smartconfig.git"
@@ -65,9 +70,8 @@
     "workflow improvement",
     "persistent storage"
   ],
-  "scripts": {
-    "test": "(tstest test/ --verbose --logfile --timeout 20)",
-    "build": "(tsbuild --web --allowimplicitany)",
-    "buildDocs": "tsdoc"
+  "packageManager": "pnpm@10.11.0+sha512.6540583f41cc5f628eb3d9773ecee802f4f9ef9923cc45b69890fb47991d4b092964694ec3a4f738a420c918a333062c8b925d312f42e4f0c263eb603551f977",
+  "pnpm": {
+    "overrides": {}
   }
-}
+}

package/readme.md

@@ -1,517 +1,322 @@
 # @push.rocks/smartconfig 🚀
 
-**Supercharge your npm projects with powerful configuration management, tool orchestration, and persistent key-value storage.**
+A comprehensive TypeScript configuration management library providing centralized tool configs, persistent key-value storage, and powerful environment variable mapping with automatic type conversions.
+
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
 
 ## Install 📦
 
 ```bash
-# Using npm
 npm install @push.rocks/smartconfig --save
-
-# Using pnpm (recommended)
+# or
 pnpm add @push.rocks/smartconfig
 ```
 
-## Overview 🎯
+## Quick Start ⚡
+
+```typescript
+import { Smartconfig, AppData, KeyValueStore } from '@push.rocks/smartconfig';
 
-`@push.rocks/smartconfig` is your Swiss Army knife for npm project configuration. It eliminates configuration sprawl by centralizing tool settings, providing intelligent key-value storage, and offering powerful environment variable mapping with automatic type conversions.
+// 1. Read tool config from .smartconfig.json
+const sc = new Smartconfig();
+const eslintOpts = sc.dataFor('eslint', { extends: 'standard' });
 
-### Why smartconfig? 
+// 2. Map env vars to typed config (with auto-conversion)
+const appData = await AppData.createAndInit<{ port: number; debug: boolean }>({
+  envMapping: {
+    port: 'PORT',
+    debug: 'boolean:DEBUG',
+  },
+});
 
-- **🎛️ Centralized Configuration**: Manage all your tool configs in one `.smartconfig.json` file
-- **💾 Persistent Storage**: Smart key-value store with multiple storage strategies
-- **🔐 Environment Mapping**: Sophisticated env var handling with automatic type conversion
-- **🏗️ TypeScript First**: Full type safety and IntelliSense support
-- **⚡ Zero Config**: Works out of the box with sensible defaults
-- **🔄 Reactive**: Built-in change detection and observables
+// 3. Persist data between runs
+const kv = new KeyValueStore({ typeArg: 'userHomeDir', identityArg: 'myapp' });
+await kv.writeKey('lastRun', Date.now());
+```
 
-## Core Concepts 🏗️
+## Three Core Classes 🏗️
 
-### 1. Smartconfig Configuration Management
+### 1. `Smartconfig` — Centralized Tool Configuration
 
-Stop scattering configuration across dozens of files. Centralize everything in `.smartconfig.json`:
+Reads a `.smartconfig.json` file from a project directory and merges its contents with your defaults. One file, every tool.
 
 ```typescript
 import { Smartconfig } from '@push.rocks/smartconfig';
 
-// Initialize with current directory
-const smartconfig = new Smartconfig();
+const sc = new Smartconfig();              // uses cwd
+const sc2 = new Smartconfig('/my/project'); // or specify a path
 
-// Or specify a custom path
-const smartconfig = new Smartconfig('/path/to/project');
-
-// Get merged configuration for any tool
-const eslintConfig = smartconfig.dataFor<EslintConfig>('eslint', {
-  // Default values if not in .smartconfig.json
-  extends: 'standard',
-  rules: {}
+const prettierConfig = sc.dataFor<PrettierConfig>('prettier', {
+  semi: false,
+  singleQuote: true,
 });
 ```
 
-**.smartconfig.json example:**
+**`.smartconfig.json`** example:
+
 ```json
 {
-  "eslint": {
-    "extends": "@company/eslint-config",
-    "rules": {
-      "no-console": "warn"
-    }
-  },
   "prettier": {
-    "semi": false,
-    "singleQuote": true
+    "semi": true,
+    "printWidth": 120
+  },
+  "eslint": {
+    "extends": "@company/eslint-config"
   }
 }
 ```
 
-### 2. KeyValueStore - Persistent Data Storage
+Values from the file override the defaults you pass in. Missing keys fall back to your defaults.
 
-A flexible key-value store that persists data between script executions:
+**Properties:**
+- `smartconfigJsonExists: boolean` — whether `.smartconfig.json` was found
+- `smartconfigJsonData: any` — the parsed JSON contents
+
+**Methods:**
+- `dataFor<T>(toolName: string, defaults: T): T` — returns merged config
+
+---
+
+### 2. `KeyValueStore<T>` — Persistent Data Storage
+
+A generic, typed key-value store that persists JSON to disk (or stays in-memory for tests). Supports change detection via RxJS observables.
 
 ```typescript
 import { KeyValueStore } from '@push.rocks/smartconfig';
 
-interface UserSettings {
+interface Settings {
   username: string;
-  apiKey: string;
-  preferences: {
-    theme: 'light' | 'dark';
-    notifications: boolean;
-  };
+  theme: 'light' | 'dark';
 }
 
-// Different storage strategies
-const kvStore = new KeyValueStore<UserSettings>({
-  typeArg: 'userHomeDir',  // Store in user's home directory
+// Store in ~/.smartconfig/kv/
+const kv = new KeyValueStore<Settings>({
+  typeArg: 'userHomeDir',
   identityArg: 'myApp',
-  mandatoryKeys: ['username', 'apiKey']
+  mandatoryKeys: ['username'],
 });
 
-// Write operations
-await kvStore.writeKey('username', 'john_doe');
-await kvStore.writeKey('preferences', {
-  theme: 'dark',
-  notifications: true
-});
+await kv.writeKey('username', 'jane');
+await kv.writeKey('theme', 'dark');
 
-// Read operations
-const username = await kvStore.readKey('username');
-const allData = await kvStore.readAll();
+const user = await kv.readKey('username'); // 'jane'
+const all = await kv.readAll();            // { username: 'jane', theme: 'dark' }
 
-// Check for missing mandatory keys
-const missingKeys = await kvStore.getMissingMandatoryKeys();
-if (missingKeys.length > 0) {
-  console.log('Missing required configuration:', missingKeys);
-}
-
-// Wait for keys to be present
-await kvStore.waitForKeysPresent(['apiKey']);
+// React to changes
+kv.changeSubject.subscribe((data) => console.log('changed:', data));
 ```
 
-**Storage Types:**
-- `userHomeDir`: Store in user's home directory
-- `custom`: Specify your own path
-- `ephemeral`: In-memory only (perfect for testing)
+**Storage types:**
+
+| `typeArg` | Where it goes | Use case |
+|-----------|--------------|----------|
+| `'userHomeDir'` | `~/.smartconfig/kv/<identity>.json` | CLI tools, per-user state |
+| `'custom'` | Your path (file or directory) | App data, project-local state |
+| `'ephemeral'` | Memory only — nothing on disk | Tests |
+
+**Methods:**
+
+| Method | Description |
+|--------|------------|
+| `readKey(key)` | Read a single value |
+| `writeKey(key, value)` | Write a single value |
+| `readAll()` | Read everything |
+| `writeAll(obj)` | Merge an object into the store |
+| `deleteKey(key)` | Remove a key |
+| `reset()` | Wipe all keys (synced to disk) |
+| `wipe()` | Delete the backing file entirely |
+| `getMissingMandatoryKeys()` | Returns keys declared mandatory but not yet set |
+| `waitForKeysPresent(keys)` | Returns a Promise that resolves once all listed keys exist |
+| `waitForAndGetKey(key)` | Waits for a key, then returns its value |
+
+---
 
-### 3. AppData - Advanced Environment Management 🌟
+### 3. `AppData<T>` — Environment Variable Mapping 🌟
 
-The crown jewel of smartconfig - sophisticated environment variable mapping with automatic type conversion:
+The flagship class. Maps environment variables (or hardcoded values) into a typed config object with automatic type conversions, nested object support, and smart storage path selection.
 
 ```typescript
 import { AppData } from '@push.rocks/smartconfig';
 
-interface AppConfig {
+interface Config {
   apiUrl: string;
   apiKey: string;
-  port: number;
   features: {
     analytics: boolean;
     payment: boolean;
   };
-  cache: {
-    ttl: number;
-    redis: {
-      host: string;
-      password: string;
-    };
+  redis: {
+    host: string;
+    password: string;
   };
 }
 
-const appData = await AppData.createAndInit<AppConfig>({
-  dirPath: '/app/config',  // Optional: defaults to smart path selection
-  requiredKeys: ['apiKey', 'apiUrl'],
+const appData = await AppData.createAndInit<Config>({
+  requiredKeys: ['apiKey'],
   envMapping: {
-    apiUrl: 'API_URL',                    // Simple mapping
-    apiKey: 'hard:development-key-123',   // Hardcoded value
-    port: 'hard:3000',                     // Hardcoded number
+    apiUrl: 'API_URL',                        // plain env var
+    apiKey: 'hard:dev-key-123',               // hardcoded fallback
     features: {
-      analytics: 'boolean:ENABLE_ANALYTICS',  // Force boolean conversion
-      payment: 'hard_boolean:true'            // Hardcoded boolean
+      analytics: 'boolean:ENABLE_ANALYTICS',  // converts "true"/"false" → boolean
+      payment: 'hard_boolean:true',           // hardcoded boolean
+    },
+    redis: {
+      host: 'REDIS_HOST',
+      password: 'base64:REDIS_PASSWORD_B64',  // base64-decode at load time
     },
-    cache: {
-      ttl: 'json:CACHE_CONFIG',  // Parse JSON from env var
-      redis: {
-        host: 'REDIS_HOST',
-        password: 'base64:REDIS_PASSWORD_B64'  // Decode base64
-      }
-    }
   },
   overwriteObject: {
-    // Force these values regardless of env vars
-    port: 8080
-  }
+    apiUrl: 'http://localhost:3000',           // force override after env mapping
+  },
 });
 
 const store = await appData.getKvStore();
-const apiUrl = await store.readKey('apiUrl');
+const url = await store.readKey('apiUrl');
 ```
 
-## AppData Special Cases & Conversions 🎯
+#### Mapping Prefixes
 
-### Environment Variable Prefixes
+| Prefix | What it does | Example mapping | Result |
+|--------|-------------|-----------------|--------|
+| *(none)* | Raw env var as string | `'MY_VAR'` | `process.env.MY_VAR` |
+| `hard:` | Hardcoded string | `'hard:hello'` | `"hello"` |
+| `boolean:` | Env var → `true`/`false` | `'boolean:FLAG'` | `true` or `false` |
+| `json:` | Env var → `JSON.parse()` | `'json:CONFIG'` | parsed object |
+| `base64:` | Env var → base64 decode | `'base64:SECRET'` | decoded string |
+| `hard_boolean:` | Hardcoded boolean | `'hard_boolean:false'` | `false` |
+| `hard_json:` | Hardcoded JSON | `'hard_json:{"a":1}'` | `{ a: 1 }` |
+| `hard_base64:` | Hardcoded base64 | `'hard_base64:SGVsbG8='` | `"Hello"` |
 
-AppData supports sophisticated type conversion through prefixes:
+Suffix detection also works: a mapping ending in `_JSON` or `_BASE64` triggers the corresponding transform automatically.
 
-| Prefix | Description | Example | Result |
-|--------|-------------|---------|--------|
-| `hard:` | Hardcoded value | `hard:myvalue` | `"myvalue"` |
-| `hard_boolean:` | Hardcoded boolean | `hard_boolean:true` | `true` |
-| `hard_json:` | Hardcoded JSON | `hard_json:{"key":"value"}` | `{key: "value"}` |
-| `hard_base64:` | Hardcoded base64 | `hard_base64:SGVsbG8=` | `"Hello"` |
-| `boolean:` | Env var as boolean | `boolean:FEATURE_FLAG` | `true/false` |
-| `json:` | Parse env var as JSON | `json:CONFIG_JSON` | Parsed object |
-| `base64:` | Decode env var from base64 | `base64:SECRET_B64` | Decoded string |
+#### Boolean Conversion Rules
 
-### Automatic Suffix Detection
+The `boolean:` prefix (and `hard_boolean:`) recognizes:
 
-Variables ending with certain suffixes get automatic conversion:
+- **true**: `"true"`, `"1"`, `"yes"`, `"y"`, `"on"` (case-insensitive)
+- **false**: `"false"`, `"0"`, `"no"`, `"n"`, `"off"` (case-insensitive)
 
-```typescript
-{
-  envMapping: {
-    // Automatically parsed as JSON if MY_CONFIG_JSON="{"enabled":true}"
-    config: 'MY_CONFIG_JSON',
-    
-    // Automatically decoded from base64 if SECRET_KEY_BASE64="SGVsbG8="
-    secret: 'SECRET_KEY_BASE64'
-  }
-}
-```
+#### Nested Objects
 
-### Complex Examples
+Mapping values can be objects — they are resolved recursively:
 
 ```typescript
-const appData = await AppData.createAndInit({
-  envMapping: {
-    // Simple environment variable
-    apiUrl: 'API_URL',
-    
-    // Hardcoded values with type conversion
-    debugMode: 'hard_boolean:false',
-    maxRetries: 'hard:5',
-    defaultConfig: 'hard_json:{"timeout":30,"retries":3}',
-    
-    // Environment variables with conversion
-    features: 'json:FEATURE_FLAGS',  // Expects: {"feature1":true,"feature2":false}
-    isProduction: 'boolean:IS_PROD', // Expects: "true" or "false"
-    apiSecret: 'base64:API_SECRET',  // Expects: base64 encoded string
-    
-    // Nested structures
-    database: {
-      host: 'DB_HOST',
-      port: 'hard:5432',
-      credentials: {
-        user: 'DB_USER',
-        password: 'base64:DB_PASSWORD_ENCODED',
-        ssl: 'boolean:DB_USE_SSL'
-      }
-    }
+envMapping: {
+  database: {
+    host: 'DB_HOST',
+    port: 'hard:5432',
+    credentials: {
+      user: 'DB_USER',
+      password: 'base64:DB_PASS_B64',
+      ssl: 'boolean:DB_SSL',
+    },
   },
-  
-  // Override any env mappings
-  overwriteObject: {
-    debugMode: true,  // Force debug mode regardless of env
-    database: {
-      host: 'localhost'  // Force localhost for development
-    }
-  }
-});
-```
-
-### Boolean Conversion Rules
-
-AppData intelligently handles boolean conversions:
-
-1. **String "true"/"false"**: Converted to boolean
-2. **With `boolean:` prefix**: Any env var value is converted (`"true"` → `true`, anything else → `false`)
-3. **With `hard_boolean:` prefix**: Hardcoded boolean value
-4. **Regular env vars**: Strings remain strings unless prefixed
-
-```typescript
-// Environment: FEATURE_A="true", FEATURE_B="yes", FEATURE_C="1"
-{
-  envMapping: {
-    featureA: 'FEATURE_A',           // Result: "true" (string)
-    featureB: 'boolean:FEATURE_B',   // Result: false (only "true" → true)
-    featureC: 'boolean:FEATURE_C',   // Result: false (only "true" → true)
-    featureD: 'hard_boolean:true'    // Result: true (hardcoded)
-  }
-}
-```
-
-### Static Helper Functions
-
-AppData provides convenient static methods for directly accessing and converting environment variables without creating an instance:
-
-```typescript
-import { AppData } from '@push.rocks/smartconfig';
-
-// Get environment variable as boolean
-const isEnabled = await AppData.valueAsBoolean('FEATURE_ENABLED');
-// Returns: true if "true", false otherwise
-
-// Get environment variable as parsed JSON
-interface Config {
-  timeout: number;
-  retries: number;
 }
-const config = await AppData.valueAsJson<Config>('SERVICE_CONFIG');
-// Returns: Parsed object or undefined
-
-// Get environment variable as base64 decoded string
-const secret = await AppData.valueAsBase64('ENCODED_SECRET');
-// Returns: Decoded string or undefined
-
-// Get environment variable as string
-const apiUrl = await AppData.valueAsString('API_URL');
-// Returns: String value or undefined
-
-// Get environment variable as number
-const port = await AppData.valueAsNumber('PORT');
-// Returns: Number value or undefined
 ```
 
-These static methods are perfect for:
-- Quick environment variable access without setup
-- Simple type conversions in utility functions
-- One-off configuration checks
-- Scenarios where you don't need the full AppData instance
-
-## Advanced Patterns 🎨
-
-### Reactive Configuration
+#### Smart Storage Path
 
-Subscribe to configuration changes:
+When no `dirPath` is specified, AppData auto-selects:
 
-```typescript
-const kvStore = new KeyValueStore<Config>({
-  typeArg: 'custom',
-  identityArg: 'myApp'
-});
+1. `/app/data` — if it exists (containers)
+2. `/data` — if it exists (alternate container path)
+3. `.nogit/appdata` — local dev fallback
 
-// Subscribe to changes
-kvStore.changeSubject.subscribe((newData) => {
-  console.log('Configuration changed:', newData);
-});
+Or pass `ephemeral: true` for zero disk I/O (great for tests).
 
-// Changes trigger notifications
-await kvStore.writeKey('theme', 'dark');
-```
+#### Static Helpers
 
-### Testing with Ephemeral Storage
-
-Perfect for unit tests - no file system pollution:
+Quick one-shot env var reads without creating an AppData instance:
 
 ```typescript
-const testStore = new KeyValueStore<TestData>({
-  typeArg: 'ephemeral',
-  identityArg: 'test'
-});
-
-// All operations work normally, but nothing persists to disk
-await testStore.writeKey('testKey', 'testValue');
+const isEnabled = await AppData.valueAsBoolean('FEATURE_FLAG');
+const config    = await AppData.valueAsJson<MyType>('CONFIG_JSON');
+const secret    = await AppData.valueAsBase64('ENCODED_SECRET');
+const url       = await AppData.valueAsString('API_URL');
+const port      = await AppData.valueAsNumber('PORT');
 ```
 
-### Smart Path Resolution
-
-AppData automatically selects the best storage location:
+#### Instance Methods
 
-1. Checks for `/app/data` (containerized environments)
-2. Falls back to `/data` (alternate container path)
-3. Uses `.nogit/appdata` (local development)
+| Method | Description |
+|--------|------------|
+| `getKvStore()` | Returns the underlying `KeyValueStore<T>` |
+| `logMissingKeys()` | Logs and returns any required keys that are missing |
+| `waitForAndGetKey(key)` | Blocks until a key is present, then returns it |
 
-```typescript
-// Automatic path selection
-const appData = await AppData.createAndInit({
-  // No dirPath specified - smart detection
-  requiredKeys: ['apiKey']
-});
+---
 
-// Or force ephemeral for testing
-const testData = await AppData.createAndInit({
-  ephemeral: true,  // No disk persistence
-  requiredKeys: ['testKey']
-});
-```
+## Security 🔐
 
-### Waiting for Configuration
+AppData automatically redacts sensitive values in its console logs. Keys matching patterns like `secret`, `token`, `password`, `api`, `auth`, `jwt`, etc. are truncated. JWT tokens (starting with `eyJ`) are also detected and shortened. Your actual stored values are never modified — only log output is redacted.
 
-Block until required configuration is available:
-
-```typescript
-const appData = await AppData.createAndInit<Config>({
-  requiredKeys: ['apiKey', 'apiUrl']
-});
-
-// Wait for specific key
-const apiKey = await appData.waitForAndGetKey('apiKey');
-
-// Check missing keys
-const missingKeys = await appData.logMissingKeys();
-// Logs: "The following mandatory keys are missing in the appdata:
-//        -> apiKey,
-//        -> apiUrl"
-```
+---
 
 ## Real-World Example 🌍
 
-Here's a complete example of a CLI tool using smartconfig:
-
 ```typescript
 import { Smartconfig, AppData, KeyValueStore } from '@push.rocks/smartconfig';
 
 interface CliConfig {
   githubToken: string;
-  openaiKey: string;
   model: 'gpt-3' | 'gpt-4';
-  cache: {
-    enabled: boolean;
-    ttl: number;
-  };
-}
-
-class MyCLI {
-  private smartconfig: Smartconfig;
-  private appData: AppData<CliConfig>;
-  private cache: KeyValueStore<{[key: string]: any}>;
-
-  async initialize() {
-    // Load tool configuration
-    this.smartconfig = new Smartconfig();
-    const config = this.smartconfig.dataFor<any>('mycli', {
-      defaultModel: 'gpt-3'
-    });
-
-    // Setup app data with env mapping
-    this.appData = await AppData.createAndInit<CliConfig>({
-      requiredKeys: ['githubToken', 'openaiKey'],
-      envMapping: {
-        githubToken: 'GITHUB_TOKEN',
-        openaiKey: 'base64:OPENAI_KEY_ENCODED',
-        model: 'hard:gpt-4',
-        cache: {
-          enabled: 'boolean:ENABLE_CACHE',
-          ttl: 'hard:3600'
-        }
-      }
-    });
-
-    // Initialize cache
-    this.cache = new KeyValueStore({
-      typeArg: 'userHomeDir',
-      identityArg: 'mycli-cache'
-    });
-
-    // Check for missing configuration
-    const missingKeys = await this.appData.logMissingKeys();
-    if (missingKeys.length > 0) {
-      console.error('Please configure the missing keys');
-      process.exit(1);
-    }
-  }
-
-  async run() {
-    await this.initialize();
-    
-    const config = await this.appData.getKvStore();
-    const settings = await config.readAll();
-    
-    console.log(`Using model: ${settings.model}`);
-    console.log(`Cache enabled: ${settings.cache.enabled}`);
-    
-    // Use the configuration...
-  }
+  cache: { enabled: boolean; ttl: number };
 }
 
-// Run the CLI
-const cli = new MyCLI();
-cli.run();
-```
-
-## API Reference 📚
-
-### Smartconfig Class
-
-```typescript
-new Smartconfig(cwdArg?: string)
-```
-- `cwdArg`: Optional working directory path
-
-**Methods:**
-- `dataFor<T>(toolName: string, defaultOptions: T): T` - Get merged configuration
-
-### KeyValueStore Class
+// Tool-level config from .smartconfig.json
+const sc = new Smartconfig();
+const toolDefaults = sc.dataFor('mycli', { defaultModel: 'gpt-3' });
 
-```typescript
-new KeyValueStore<T>(options: {
-  typeArg: 'custom' | 'userHomeDir' | 'ephemeral';
-  identityArg: string;
-  customPath?: string;
-  mandatoryKeys?: Array<keyof T>;
-})
-```
+// Env-mapped runtime config
+const appData = await AppData.createAndInit<CliConfig>({
+  requiredKeys: ['githubToken'],
+  envMapping: {
+    githubToken: 'GITHUB_TOKEN',
+    model: 'hard:gpt-4',
+    cache: {
+      enabled: 'boolean:ENABLE_CACHE',
+      ttl: 'hard:3600',
+    },
+  },
+});
 
-**Methods:**
-- `readKey(key: string): Promise<T>` - Read single value
-- `writeKey(key: string, value: T): Promise<void>` - Write single value
-- `readAll(): Promise<T>` - Read all values
-- `writeAll(data: T): Promise<void>` - Write all values
-- `deleteKey(key: string): Promise<void>` - Delete a key
-- `getMissingMandatoryKeys(): Promise<string[]>` - Check missing required keys
-- `waitForKeysPresent(keys: string[]): Promise<void>` - Wait for keys
+// Persistent user-level cache
+const cache = new KeyValueStore({
+  typeArg: 'userHomeDir',
+  identityArg: 'mycli-cache',
+});
 
-### AppData Class
+// Check mandatory keys
+const missing = await appData.logMissingKeys();
+if (missing.length > 0) {
+  console.error('Missing config — set these env vars and retry.');
+  process.exit(1);
+}
 
-```typescript
-await AppData.createAndInit<T>(options: {
-  dirPath?: string;
-  requiredKeys?: Array<keyof T>;
-  ephemeral?: boolean;
-  envMapping?: PartialDeep<T>;
-  overwriteObject?: PartialDeep<T>;
-})
+const store = await appData.getKvStore();
+const settings = await store.readAll();
+console.log(`Model: ${settings.model}, Cache: ${settings.cache.enabled}`);
 ```
 
-**Methods:**
-- `getKvStore(): Promise<KeyValueStore<T>>` - Get underlying store
-- `logMissingKeys(): Promise<Array<keyof T>>` - Log and return missing keys
-- `waitForAndGetKey<K>(key: K): Promise<T[K]>` - Wait for and retrieve key
-
 ## License and Legal Information
 
-This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 
 ### Trademarks
 
-This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
 
 ### Company Information
 
-Task Venture Capital GmbH  
-Registered at District court Bremen HRB 35230 HB, Germany
+Task Venture Capital GmbH
+Registered at District Court Bremen HRB 35230 HB, Germany
 
-For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
 
-By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartconfig',
-  version: '6.0.1',
+  version: '6.1.0',
   description: 'A comprehensive configuration management library providing key-value storage, environment variable mapping, and tool configuration.'
 }