@kb-labs/core-config 1.0.0

package/README.md

@@ -0,0 +1,338 @@
+# @kb-labs/core-config
+
+> **Core configuration system for KB Labs products with 6-layer merging, YAML/JSON support, and comprehensive tracing.** Provides deterministic configuration resolution with detailed merge traces for debugging.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-18.18.0+-green.svg)](https://nodejs.org/)
+[![pnpm](https://img.shields.io/badge/pnpm-9.0.0+-orange.svg)](https://pnpm.io/)
+
+## 🎯 Vision & Purpose
+
+**@kb-labs/core-config** is the foundation of KB Labs configuration system. It implements a sophisticated 6-layer configuration merging strategy that allows products to have defaults, profile overrides, preset configurations, workspace settings, local overrides, and CLI arguments - all merged deterministically with full traceability.
+
+## 🏗️ Architecture
+
+### Core Components
+
+#### `getProductConfig()` - Main Configuration Resolver
+
+- **Purpose**: Resolves product configuration by merging 6 layers
+- **Responsibilities**: 
+  - Find workspace root
+  - Load workspace config
+  - Resolve profile defaults
+  - Load preset defaults
+  - Load local config
+  - Merge with CLI overrides
+  - Return merged config with trace
+- **Dependencies**: `core-types`, `yaml`, `zod`, `ajv`
+- **Exports**: `ProductConfigResult<T>` with config and trace
+
+#### `layeredMergeWithTrace()` - Merge Engine
+
+- **Purpose**: Merges configuration layers with detailed tracing
+- **Responsibilities**: 
+  - Deep merge objects
+  - Track merge operations
+  - Generate merge trace
+- **Dependencies**: None (pure function)
+- **Exports**: `LayeredMergeResult` with merged config and trace
+
+#### Profile Resolution System
+
+- **Purpose**: Resolves Profiles v2 with scope selection
+- **Responsibilities**: 
+  - Load profile manifests
+  - Resolve profile extends
+  - Select scopes
+  - Extract profile defaults
+- **Dependencies**: `zod` for validation
+- **Exports**: `resolveProfile()`, `selectProfileScope()`
+
+### Design Patterns
+
+- **Layered Architecture**: 6-layer configuration system
+- **Strategy Pattern**: Different merge strategies for different layer types
+- **Cache Pattern**: LRU cache for file system reads
+- **Builder Pattern**: Configuration built layer by layer
+
+### Data Flow
+
+```
+getProductConfig({ product, ... })
+    │
+    ├──► findNearestConfig() → workspace root
+    ├──► readWorkspaceConfig() → workspace config
+    ├──► resolveProfile() → profile defaults
+    ├──► resolvePreset() → preset defaults
+    ├──► readLocalConfig() → local config
+    ├──► layeredMergeWithTrace() → merged config + trace
+    └──► return { config, trace }
+```
+
+### State Management
+
+- **State Type**: Local (per function call) + cached (LRU)
+- **State Storage**: Memory (LRU cache for file reads)
+- **State Lifecycle**: Created per call, cached for performance
+- **State Persistence**: No persistence (stateless API)
+
+### Concurrency Model
+
+- **Single-threaded**: All operations are async but single-threaded
+- **Thread Safety**: N/A (Node.js single-threaded event loop)
+- **Race Conditions**: None (stateless API)
+- **Deadlocks**: None
+
+### Error Handling Strategy
+
+- **Error Types**: `KbError` with error codes and hints
+- **Error Propagation**: Errors thrown and caught by caller
+- **Error Recovery**: No automatic recovery (caller must handle)
+- **Error Logging**: Diagnostics array for non-fatal issues
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pnpm add @kb-labs/core-config
+```
+
+### Basic Usage
+
+```typescript
+import { getProductConfig } from '@kb-labs/core-config';
+
+const result = await getProductConfig({
+  cwd: process.cwd(),
+  product: 'aiReview',
+  cli: { debug: true }
+}, schema);
+
+console.log(result.config); // Merged configuration
+console.log(result.trace);   // Detailed merge trace
+```
+
+## ✨ Features
+
+- **YAML/JSON Support**: Automatic format detection and parsing
+- **Find-up Resolution**: Walks up directory tree to find config files
+- **Layered Merge**: Deterministic configuration merging with detailed trace
+- **Product Normalization**: Consistent kebab-case (FS) ↔ camelCase (code) mapping
+- **LRU Caching**: Filesystem read caching with invalidation
+- **Error Handling**: Standardized errors with helpful hints
+- **Schema Versioning**: All configs include `schemaVersion: "1.0"`
+
+## API
+
+### Core Functions
+
+```typescript
+import { 
+  getProductConfig, 
+  explainProductConfig, 
+  readConfigFile,
+  findNearestConfig,
+  clearCaches 
+} from '@kb-labs/core-config';
+
+// Get product configuration with trace
+const result = await getProductConfig({
+  cwd: '/path/to/project',
+  product: 'aiReview',
+  cli: { debug: true }
+}, schema);
+
+console.log(result.config); // Merged configuration
+console.log(result.trace);   // Detailed merge trace
+
+// Explain configuration without resolving
+const explanation = await explainProductConfig({
+  cwd: '/path/to/project',
+  product: 'aiReview'
+}, schema);
+
+// Read config file with format detection
+const config = await readConfigFile('kb-labs.config.yaml');
+
+// Find nearest config file
+const { path, tried } = await findNearestConfig('/path/to/project');
+
+// Clear caches (useful for tests)
+clearCaches();
+```
+
+### Product Normalization
+
+```typescript
+import { toFsProduct, toConfigProduct, ProductId } from '@kb-labs/core-config';
+
+// Convert to filesystem format
+toFsProduct('aiReview'); // 'ai-review'
+toFsProduct('aiDocs');   // 'ai-docs'
+
+// Convert to code format
+toConfigProduct('ai-review'); // 'aiReview'
+toConfigProduct('ai-docs');   // 'aiDocs'
+```
+
+### Error Handling
+
+```typescript
+import { KbError, getExitCode } from '@kb-labs/core-config';
+
+try {
+  const config = await getProductConfig(opts, schema);
+} catch (error) {
+  if (error instanceof KbError) {
+    console.error(error.message);
+    console.error('Hint:', error.hint);
+    process.exit(getExitCode(error));
+  }
+}
+```
+
+## Configuration Layers
+
+The system merges configuration in this order (later layers override earlier ones):
+
+1. **Runtime defaults** - Built-in defaults for each product
+2. **Profile defaults** - From profile manifest defaults
+3. **Preset defaults** - From org preset package
+4. **Workspace config** - From `kb-labs.config.(json|yaml)`
+5. **Local config** - From `.kb/<product>/<product>.config.json`
+6. **CLI overrides** - From command line arguments
+
+## Configuration Files
+
+### Workspace Config (`kb-labs.config.yaml`)
+
+```yaml
+schemaVersion: "1.0"
+profiles:
+  default: "node-ts-lib@1.2.0"
+  backend: "node-ts-lib@1.2.0"
+products:
+  ai-review:
+    enabled: true
+    rules: ["security", "performance"]
+  devlink:
+    watch: true
+    build: true
+```
+
+### Local Config (`.kb/ai-review/ai-review.config.json`)
+
+```json
+{
+  "$schema": "https://schemas.kb-labs.dev/config.schema.json",
+  "schemaVersion": "1.0",
+  "enabled": true,
+  "rules": ["custom-rule"],
+  "settings": {
+    "debug": true
+  }
+}
+```
+
+## Error Codes
+
+| Code | Exit Code | Description |
+|------|-----------|-------------|
+| `ERR_CONFIG_NOT_FOUND` | 2 | Config file not found |
+| `ERR_CONFIG_INVALID` | 1 | Invalid config syntax |
+| `ERR_PRESET_NOT_RESOLVED` | 1 | Preset package not found |
+| `ERR_PROFILE_INCOMPATIBLE` | 1 | Profile version incompatible |
+
+## Caching
+
+The system uses LRU caching for filesystem reads:
+
+- **Key**: `absPath|mtime|size`
+- **Max Size**: 100 entries
+- **Invalidation**: Automatic on file change
+- **Clear**: Use `clearCaches()` for tests
+
+## Examples
+
+### Basic Usage
+
+```typescript
+import { getProductConfig } from '@kb-labs/core-config';
+
+const config = await getProductConfig({
+  cwd: process.cwd(),
+  product: 'aiReview',
+  cli: { debug: true }
+}, aiReviewSchema);
+
+console.log('AI Review config:', config.config);
+console.log('Merge trace:', config.trace);
+```
+
+### CLI Integration
+
+```typescript
+import { getProductConfig, KbError, getExitCode } from '@kb-labs/core-config';
+
+try {
+  const result = await getProductConfig({
+    cwd: process.cwd(),
+    product: 'aiReview',
+    cli: cliArgs
+  }, schema);
+  
+  console.log(JSON.stringify(result.config, null, 2));
+} catch (error) {
+  if (error instanceof KbError) {
+    console.error(`Error: ${error.message}`);
+    if (error.hint) {
+      console.error(`Hint: ${error.hint}`);
+    }
+    process.exit(getExitCode(error));
+  }
+  throw error;
+}
+```
+
+### Testing
+
+```typescript
+import { clearCaches } from '@kb-labs/core-config';
+
+beforeEach(() => {
+  clearCaches(); // Clear caches between tests
+});
+```
+
+## 🔧 Configuration
+
+### Configuration Options
+
+The 6-layer configuration system:
+
+1. **Runtime defaults** - Built-in defaults for each product
+2. **Profile defaults** - From profile manifest defaults
+3. **Preset defaults** - From org preset package (`$extends`)
+4. **Workspace config** - From `kb-labs.config.(json|yaml)`
+5. **Local config** - From `.kb/<product>/<product>.config.json`
+6. **CLI overrides** - From command line arguments
+
+### Environment Variables
+
+- None (all configuration via files and options)
+
+### Default Values
+
+- **Cache Size**: 100 entries (LRU)
+- **Config Format**: Auto-detected (YAML/JSON)
+- **Schema Version**: "1.0"
+
+## 🤝 Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for development guidelines.
+
+## 📄 License
+
+KB Public License v1.1 © KB Labs

package/dist/chunk-A2WE2JZW.js

@@ -0,0 +1,80 @@
+import { promises } from 'fs';
+import { dirname, resolve } from 'path';
+
+// src/utils/fs-atomic.ts
+
+// src/errors/kb-error.ts
+var KbError = class extends Error {
+  constructor(code, message, hint, meta) {
+    super(message);
+    this.code = code;
+    this.hint = hint;
+    this.meta = meta;
+    this.name = "KbError";
+  }
+};
+function getExitCode(err) {
+  if (err.code === "ERR_FORBIDDEN") {
+    return 3;
+  }
+  if (err.code === "ERR_CONFIG_NOT_FOUND") {
+    return 2;
+  }
+  if (err.code === "ERR_CONFIG_EXISTS_CONFLICT") {
+    return 2;
+  }
+  if (err.code === "ERR_PATH_OUTSIDE_WORKSPACE") {
+    return 2;
+  }
+  if (err.code.startsWith("ERR_")) {
+    return 1;
+  }
+  return 1;
+}
+var ERROR_HINTS = {
+  ERR_CONFIG_NOT_FOUND: "Create .kb/kb-labs.config.yaml or run: kb init",
+  ERR_CONFIG_INVALID: "Check configuration syntax and required fields",
+  ERR_CONFIG_EXISTS_CONFLICT: "Use --force to overwrite existing configuration",
+  ERR_PATH_OUTSIDE_WORKSPACE: "Check cwd or use a relative path within the workspace",
+  ERR_PRESET_NOT_RESOLVED: "Install the required preset package or check network connectivity",
+  ERR_PROFILE_INCOMPATIBLE: "Profile version is incompatible with current system",
+  ERR_PROFILE_NOT_DEFINED: "Add profiles[] to kb.config.json or pass --profile=<id>",
+  ERR_PROFILE_RESOLVE_FAILED: "Profile registry unavailable. Define profiles[] inside kb.config.json or use workspace presets.",
+  ERR_PROFILE_EXTENDS_FAILED: "Profile extends failed. Check extends reference or install required preset/package.",
+  ERR_PROFILE_SCOPE_NOT_FOUND: "Scope not found. Use --scope=<id> with one of the configured scopes.",
+  ERR_PROFILE_SCOPE_CONFLICT: "Multiple scopes matched. Specify --scope=<id> explicitly.",
+  ERR_PROFILE_INVALID_FORMAT: "Update profiles[] in kb.config.json (Profiles v2) or rerun your plugin setup command.",
+  ERR_ARTIFACT_LIMIT_EXCEEDED: "Remove or split large artifacts, or reduce artifact count",
+  ERR_FORBIDDEN: "Add role in policy.overrides or use preset..."
+};
+async function writeFileAtomic(path, data) {
+  const tmp = `${path}.tmp-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  try {
+    await promises.mkdir(dirname(path), { recursive: true });
+    await promises.mkdir(dirname(tmp), { recursive: true });
+    await promises.writeFile(tmp, data);
+    await promises.rename(tmp, path);
+  } catch (error) {
+    try {
+      await promises.unlink(tmp);
+    } catch {
+    }
+    throw error;
+  }
+}
+function ensureWithinWorkspace(targetPath, workspaceRoot) {
+  const absTarget = resolve(targetPath);
+  const absRoot = resolve(workspaceRoot);
+  if (!absTarget.startsWith(absRoot)) {
+    throw new KbError(
+      "ERR_PATH_OUTSIDE_WORKSPACE",
+      `Refusing to write outside workspace: ${targetPath}`,
+      "Check cwd or use a relative path within the workspace",
+      { targetPath, workspaceRoot }
+    );
+  }
+}
+
+export { ERROR_HINTS, KbError, ensureWithinWorkspace, getExitCode, writeFileAtomic };
+//# sourceMappingURL=chunk-A2WE2JZW.js.map
+//# sourceMappingURL=chunk-A2WE2JZW.js.map

package/dist/chunk-A2WE2JZW.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors/kb-error.ts","../src/utils/fs-atomic.ts"],"names":["fs"],"mappings":"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","file":"chunk-A2WE2JZW.js","sourcesContent":["/**\n * @module @kb-labs/core/config/errors\n * Standardized error class for KB Labs with exit code mapping\n */\n\nexport class KbError extends Error {\n  constructor(\n    public code: string,\n    message: string,\n    public hint?: string,\n    public meta?: any\n  ) {\n    super(message);\n    this.name = 'KbError';\n  }\n}\n\n/**\n * Maps KbError codes to CLI exit codes\n */\nexport function getExitCode(err: KbError): number {\n  if (err.code === 'ERR_FORBIDDEN') {return 3;}\n  if (err.code === 'ERR_CONFIG_NOT_FOUND') {return 2;}\n  if (err.code === 'ERR_CONFIG_EXISTS_CONFLICT') {return 2;}\n  if (err.code === 'ERR_PATH_OUTSIDE_WORKSPACE') {return 2;}\n  if (err.code.startsWith('ERR_')) {return 1;}\n  return 1;\n}\n\n/**\n * Error codes with their standard hints\n */\nexport const ERROR_HINTS = {\n  ERR_CONFIG_NOT_FOUND: 'Create .kb/kb-labs.config.yaml or run: kb init',\n  ERR_CONFIG_INVALID: 'Check configuration syntax and required fields',\n  ERR_CONFIG_EXISTS_CONFLICT: 'Use --force to overwrite existing configuration',\n  ERR_PATH_OUTSIDE_WORKSPACE: 'Check cwd or use a relative path within the workspace',\n  ERR_PRESET_NOT_RESOLVED: 'Install the required preset package or check network connectivity',\n  ERR_PROFILE_INCOMPATIBLE: 'Profile version is incompatible with current system',\n  ERR_PROFILE_NOT_DEFINED: 'Add profiles[] to kb.config.json or pass --profile=<id>',\n  ERR_PROFILE_RESOLVE_FAILED: 'Profile registry unavailable. Define profiles[] inside kb.config.json or use workspace presets.',\n  ERR_PROFILE_EXTENDS_FAILED: 'Profile extends failed. Check extends reference or install required preset/package.',\n  ERR_PROFILE_SCOPE_NOT_FOUND: 'Scope not found. Use --scope=<id> with one of the configured scopes.',\n  ERR_PROFILE_SCOPE_CONFLICT: 'Multiple scopes matched. Specify --scope=<id> explicitly.',\n  ERR_PROFILE_INVALID_FORMAT: 'Update profiles[] in kb.config.json (Profiles v2) or rerun your plugin setup command.',\n  ERR_ARTIFACT_LIMIT_EXCEEDED: 'Remove or split large artifacts, or reduce artifact count',\n  ERR_FORBIDDEN: 'Add role in policy.overrides or use preset...',\n} as const;\n\nexport type ErrorCode = keyof typeof ERROR_HINTS;\n","/**\n * @module @kb-labs/core/config/utils/fs-atomic\n * Atomic file write operations using tmp+rename pattern\n */\n\nimport { promises as fs } from 'node:fs';\nimport { resolve } from 'node:path';\nimport { KbError } from '../errors/kb-error';\nimport { dirname } from 'node:path';\n\n/**\n * Write file atomically using tmp+rename pattern\n * This ensures that the file is never partially written in case of crashes\n */\nexport async function writeFileAtomic(\n  path: string,\n  data: string | Uint8Array\n): Promise<void> {\n  const tmp = `${path}.tmp-${Date.now()}-${Math.random().toString(36).slice(2)}`;\n  \n  try {\n    // Ensure parent directory exists\n    await fs.mkdir(dirname(path), { recursive: true });\n    await fs.mkdir(dirname(tmp), { recursive: true });\n    \n    // Write to temp file\n    await fs.writeFile(tmp, data);\n    \n    // Atomic rename\n    await fs.rename(tmp, path);\n  } catch (error) {\n    // Clean up temp file if it exists\n    try {\n      await fs.unlink(tmp);\n    } catch {\n      // Ignore cleanup errors\n    }\n    throw error;\n  }\n}\n\n/**\n * Ensure a path is within the workspace root\n * Throws ERR_PATH_OUTSIDE_WORKSPACE if the path escapes the workspace\n */\nexport function ensureWithinWorkspace(targetPath: string, workspaceRoot: string): void {\n  const absTarget = resolve(targetPath);\n  const absRoot = resolve(workspaceRoot);\n  \n  if (!absTarget.startsWith(absRoot)) {\n    throw new KbError(\n      'ERR_PATH_OUTSIDE_WORKSPACE',\n      `Refusing to write outside workspace: ${targetPath}`,\n      'Check cwd or use a relative path within the workspace',\n      { targetPath, workspaceRoot }\n    );\n  }\n}\n\n"]}

package/dist/fs-atomic-EKSZ6G5A.js

@@ -0,0 +1,3 @@
+export { ensureWithinWorkspace, writeFileAtomic } from './chunk-A2WE2JZW.js';
+//# sourceMappingURL=fs-atomic-EKSZ6G5A.js.map
+//# sourceMappingURL=fs-atomic-EKSZ6G5A.js.map

package/dist/fs-atomic-EKSZ6G5A.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"fs-atomic-EKSZ6G5A.js"}