@kb-labs/adapters 0.5.0

package/README-TEMPLATE.md

@@ -0,0 +1,179 @@
+# @kb-labs/adapters-{name}
+
+> Part of [KB Labs](https://github.com/KirillBaranov/kb-labs) ecosystem. Works exclusively within KB Labs platform.
+
+{Short description of what this adapter does and why it exists.}
+
+## Overview
+
+| Property | Value |
+|----------|-------|
+| **Implements** | `I{Interface}` |
+| **Type** | `core` / `extension` |
+| **Requires** | `cache`, `db`, ... (or "None") |
+| **Category** | Logging / Database / Cache / EventBus / Analytics / AI / Storage |
+
+## Features
+
+- **Feature 1** - Brief description
+- **Feature 2** - Brief description
+- **Feature 3** - Brief description
+
+## Installation
+
+```bash
+pnpm add @kb-labs/adapters-{name}
+```
+
+## Configuration
+
+Add to your `kb.config.json`:
+
+```json
+{
+  "platform": {
+    "adapters": {
+      "{adapterKey}": "@kb-labs/adapters-{name}"
+    },
+    "adapterOptions": {
+      "{adapterKey}": {
+        "option1": "value1",
+        "option2": 1000
+      }
+    }
+  }
+}
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `option1` | `string` | `"default"` | Description of option1 |
+| `option2` | `number` | `1000` | Description of option2 |
+
+## Usage
+
+### Via Platform (Recommended)
+
+```typescript
+import { usePlatform } from '@kb-labs/sdk';
+
+const platform = usePlatform();
+
+// Use the adapter via platform
+await platform.{adapterKey}.method();
+```
+
+### Standalone (Testing/Development)
+
+```typescript
+import { createAdapter } from '@kb-labs/adapters-{name}';
+
+const adapter = createAdapter(
+  { option1: 'value1' },
+  { dependency: dependencyInstance }
+);
+```
+
+## How It Works
+
+{Technical explanation of how the adapter works internally. Include diagrams if helpful.}
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│   Client    │────▶│   Adapter   │────▶│   Backend   │
+└─────────────┘     └─────────────┘     └─────────────┘
+```
+
+## Dependencies
+
+This adapter requires the following adapters to be configured:
+
+| Dependency | Adapter Key | Description |
+|------------|-------------|-------------|
+| `cache` | `cache` | Cache backend for storage |
+
+> Dependencies are automatically resolved by the platform's AdapterLoader.
+
+## Adapter Manifest
+
+```typescript
+{
+  id: '{name}',
+  name: '{Human-readable Name}',
+  version: '1.0.0',
+  implements: 'I{Interface}',
+  requires: {
+    adapters: [{ id: 'cache', alias: 'cache' }],
+    platform: '>= 1.0.0',
+  },
+  capabilities: {
+    // Adapter-specific capabilities
+  },
+}
+```
+
+## Performance Considerations
+
+- **Memory**: {Memory usage notes}
+- **Latency**: {Latency expectations}
+- **Throughput**: {Throughput notes}
+
+## FAQ
+
+<details>
+<summary><strong>Q: Can I use this adapter outside KB Labs platform?</strong></summary>
+
+No. This adapter is designed specifically for KB Labs ecosystem and depends on platform interfaces and contracts. Use `createAdapter()` for standalone testing only.
+</details>
+
+<details>
+<summary><strong>Q: How do I switch between different implementations?</strong></summary>
+
+Change the adapter package in `kb.config.json`:
+
+```json
+{
+  "platform": {
+    "adapters": {
+      "{adapterKey}": "@kb-labs/adapters-{alternative-name}"
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Q: {Common question about this adapter}</strong></summary>
+
+{Answer}
+</details>
+
+## Related Adapters
+
+| Adapter | Use Case |
+|---------|----------|
+| `@kb-labs/adapters-{related1}` | Alternative for {use case} |
+| `@kb-labs/adapters-{related2}` | Complementary for {use case} |
+
+## Troubleshooting
+
+### Error: {Common error message}
+
+**Cause**: {Why this happens}
+
+**Solution**: {How to fix}
+
+```bash
+# Example fix command
+pnpm kb plugins clear-cache
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for development guidelines.
+
+## License
+
+[KB Public License v1.1](../../LICENSE) - KB Labs Team

package/README.md

@@ -0,0 +1,306 @@
+# Standard Configuration Templates
+
+This directory contains canonical configuration templates for all `@kb-labs` packages.
+
+## 📋 Available Templates
+
+### Core Configs (All Packages)
+
+| File | Purpose | Required | Customizable |
+|------|---------|----------|--------------|
+| **eslint.config.js** | Linting rules | ✅ Yes | ⚠️ Minimal |
+| **tsconfig.json** | TypeScript IDE config | ✅ Yes | ❌ No |
+| **tsconfig.build.json** | TypeScript build config | ✅ Yes | ❌ No |
+
+### Tsup Configs (Choose ONE based on package type)
+
+| Template | Package Type | Use Cases |
+|----------|--------------|-----------|
+| **tsup.config.ts** | 📦 **Library** (default) | Most packages, importable libraries |
+| **tsup.config.bin.ts** | 🔧 **Binary** | Standalone executables, CLI bins |
+| **tsup.config.cli.ts** | ⌨️ **CLI** | CLI packages with commands |
+| **tsup.config.dual.ts** | 📦🔧 **Library + Binary** | Packages with both API and bin |
+
+### Package.json Examples
+
+| Template | Purpose |
+|----------|---------|
+| **package.json.lib** | Library package example |
+| **package.json.bin** | Binary package example |
+
+## 🎯 Philosophy
+
+**Convention over Configuration**
+
+All `@kb-labs` packages MUST use these exact templates with minimal customization. This ensures:
+
+- ✅ Consistent build output across all packages
+- ✅ Predictable dependency resolution
+- ✅ Unified linting standards
+- ✅ Easy maintenance and upgrades
+
+## 📦 Usage
+
+### For New Packages
+
+#### Step 1: Choose Package Type
+
+**Library Package** (most common):
+```bash
+cp kb-labs-devkit/templates/configs/tsup.config.ts your-package/
+cp kb-labs-devkit/templates/configs/eslint.config.js your-package/
+cp kb-labs-devkit/templates/configs/tsconfig*.json your-package/
+cp kb-labs-devkit/templates/configs/package.json.lib your-package/package.json
+```
+
+**Binary Package** (standalone executables):
+```bash
+cp kb-labs-devkit/templates/configs/tsup.config.bin.ts your-package/tsup.config.ts
+cp kb-labs-devkit/templates/configs/eslint.config.js your-package/
+cp kb-labs-devkit/templates/configs/tsconfig*.json your-package/
+cp kb-labs-devkit/templates/configs/package.json.bin your-package/package.json
+```
+
+**CLI Package** (command handlers):
+```bash
+cp kb-labs-devkit/templates/configs/tsup.config.cli.ts your-package/tsup.config.ts
+cp kb-labs-devkit/templates/configs/eslint.config.js your-package/
+cp kb-labs-devkit/templates/configs/tsconfig*.json your-package/
+cp kb-labs-devkit/templates/configs/package.json.lib your-package/package.json
+```
+
+**Dual Package** (library + binary):
+```bash
+cp kb-labs-devkit/templates/configs/tsup.config.dual.ts your-package/tsup.config.ts
+cp kb-labs-devkit/templates/configs/eslint.config.js your-package/
+cp kb-labs-devkit/templates/configs/tsconfig*.json your-package/
+cp kb-labs-devkit/templates/configs/package.json.lib your-package/package.json
+# Then add "bin" field to package.json
+```
+
+#### Step 2: Customize Package Name
+```bash
+# Edit package.json and update name, description
+```
+
+### For Existing Packages
+
+```bash
+# Check for drift
+npx kb-devkit-check-configs
+
+# Auto-fix drift
+npx kb-devkit-check-configs --fix
+```
+
+## 🔧 Customization Rules
+
+### tsup.config.ts
+
+**Allowed customizations:**
+
+```typescript
+export default defineConfig({
+  ...nodePreset,
+  tsconfig: 'tsconfig.build.json', // ✅ Always required
+
+  // ✅ OK: Multiple entry points
+  entry: ['src/index.ts', 'src/cli.ts'],
+
+  // ✅ OK: Extra external deps (if really needed)
+  external: ['special-native-module'],
+
+  dts: true, // ✅ Always required
+});
+```
+
+**NOT allowed:**
+
+```typescript
+// ❌ WRONG: Don't override preset settings
+export default defineConfig({
+  format: ['esm'],        // Already in preset!
+  target: 'es2022',       // Already in preset!
+  sourcemap: true,        // Already in preset!
+  // ...
+});
+
+// ❌ WRONG: Don't disable types
+dts: false,
+
+// ❌ WRONG: Don't duplicate external deps
+external: [
+  '@kb-labs/core',  // Already in preset!
+  '@kb-labs/cli',   // Already in preset!
+],
+```
+
+### eslint.config.js
+
+**Allowed customizations:**
+
+```javascript
+export default [
+  ...nodePreset,
+  {
+    // ✅ OK: Project-specific ignores only
+    ignores: ['**/*.generated.ts']
+  }
+];
+```
+
+**NOT allowed:**
+
+```javascript
+// ❌ WRONG: Don't duplicate preset ignores
+export default [
+  ...nodePreset,
+  {
+    ignores: [
+      '**/dist/**',        // Already in preset!
+      '**/node_modules/**', // Already in preset!
+    ]
+  }
+];
+```
+
+### tsconfig.json & tsconfig.build.json
+
+**NOT customizable!**
+
+These files MUST remain identical to templates. All TypeScript configuration is standardized in DevKit presets.
+
+```json
+// ❌ WRONG: Don't override extends
+{
+  "extends": "./my-custom-base.json"
+}
+
+// ❌ WRONG: Don't add compilerOptions
+{
+  "extends": "@kb-labs/devkit/tsconfig/node.json",
+  "compilerOptions": {
+    "strict": false  // Don't override preset!
+  }
+}
+```
+
+## 🔍 Drift Detection
+
+DevKit automatically detects configuration drift:
+
+```bash
+# Check all packages
+npx kb-devkit-check-configs
+
+# Check specific package
+npx kb-devkit-check-configs --package=@kb-labs/core
+
+# Auto-fix (creates backup)
+npx kb-devkit-check-configs --fix
+
+# CI mode (fail on drift)
+npx kb-devkit-check-configs --ci
+```
+
+### Drift Detection Rules
+
+| Issue | Severity | Auto-fix |
+|-------|----------|----------|
+| Missing `dts: true` | 🔴 Error | ✅ Yes |
+| Using `dts: false` | 🔴 Error | ✅ Yes |
+| Not using `nodePreset` | 🔴 Error | ⚠️ Manual |
+| Duplicate `external` | 🟡 Warning | ✅ Yes |
+| Duplicate `ignores` | 🟡 Warning | ✅ Yes |
+| Missing templates | 🔴 Error | ✅ Yes |
+| Modified templates | 🔴 Error | ⚠️ Manual |
+
+## 📚 Examples
+
+### ✅ Good Example (Minimal Package)
+
+```typescript
+// tsup.config.ts
+import { defineConfig } from 'tsup';
+import nodePreset from '@kb-labs/devkit/tsup/node.js';
+
+export default defineConfig({
+  ...nodePreset,
+  tsconfig: 'tsconfig.build.json',
+  entry: ['src/index.ts'],
+  dts: true,
+});
+```
+
+### ✅ Good Example (CLI Package with Multiple Entries)
+
+```typescript
+// tsup.config.ts
+import { defineConfig } from 'tsup';
+import nodePreset from '@kb-labs/devkit/tsup/node.js';
+
+export default defineConfig({
+  ...nodePreset,
+  tsconfig: 'tsconfig.build.json',
+  entry: [
+    'src/index.ts',
+    'src/cli/index.ts',
+    'src/cli/commands/build.ts',
+    'src/cli/commands/test.ts',
+  ],
+  dts: true,
+});
+```
+
+### ❌ Bad Example (Over-configured)
+
+```typescript
+// tsup.config.ts
+import { defineConfig } from 'tsup';
+
+// ❌ Not using preset!
+export default defineConfig({
+  format: ['esm'],
+  target: 'es2022',
+  sourcemap: true,
+  clean: true,
+  dts: true,
+  entry: ['src/index.ts'],
+  external: [/^@kb-labs\/.*/],  // Manual external
+});
+```
+
+## 🚀 Migration Guide
+
+### From Custom Config to Standard Template
+
+1. **Backup your current config**
+   ```bash
+   cp tsup.config.ts tsup.config.ts.backup
+   ```
+
+2. **Copy standard template**
+   ```bash
+   cp kb-labs-devkit/templates/configs/tsup.config.ts .
+   ```
+
+3. **Migrate customizations** (only if needed)
+   - Compare your backup with template
+   - Extract only truly necessary customizations
+   - Add them with comments explaining why
+
+4. **Test build**
+   ```bash
+   pnpm run build
+   ```
+
+5. **Verify types**
+   ```bash
+   npx kb-devkit-check-types
+   ```
+
+## 🔗 Related
+
+- [DevKit README](../../README.md)
+- [DevKit Usage Guide](../../USAGE_GUIDE.md)
+- [ADR-0009: Unified Build Convention](../../docs/adr/0009-unified-build-convention.md)

package/docs/DOCUMENTATION.md

@@ -0,0 +1,74 @@
+# KB Labs Product Template Documentation Standard
+
+> **This document is a project-specific copy of the KB Labs Documentation Standard.**  
+> See [Main Documentation Standard](https://github.com/KirillBaranov/kb-labs/blob/main/docs/DOCUMENTATION.md) for the complete ecosystem standard.
+
+This document defines the documentation standards for **KB Labs Product Template**. This project follows the [KB Labs Documentation Standard](https://github.com/KirillBaranov/kb-labs/blob/main/docs/DOCUMENTATION.md) with the following project-specific customizations:
+
+## Project-Specific Customizations
+
+KB Labs Product Template is a zero-config starter powered by @kb-labs/devkit. Documentation should focus on:
+
+- Project scaffolding
+- Quick start guide
+- Template customization
+- Best practices for new projects
+
+## Project Documentation Structure
+
+```
+docs/
+├── DOCUMENTATION.md       # This standard (REQUIRED)
+└── adr/                    # Architecture Decision Records
+    ├── 0000-template.md   # ADR template
+    └── *.md                # ADR files
+```
+
+## Required Documentation
+
+This project requires:
+
+- [x] `README.md` in root with all required sections
+- [x] `CONTRIBUTING.md` in root with development guidelines
+- [x] `docs/DOCUMENTATION.md` (this file)
+- [x] `docs/adr/0000-template.md` (ADR template exists)
+- [x] `LICENSE` in root
+
+## Optional Documentation
+
+Consider adding:
+
+- [ ] `docs/glossary.md` - Template-specific terms
+- [ ] `docs/examples.md` - Template usage examples
+- [ ] `docs/faq.md` - Frequently asked questions
+
+## ADR Requirements
+
+All ADRs must follow the format defined in the [main standard](https://github.com/KirillBaranov/kb-labs/blob/main/docs/DOCUMENTATION.md#architecture-decision-records-adr) with:
+
+- Required metadata: Date, Status, Deciders, Last Reviewed, Tags
+- Minimum 1 tag, maximum 5 tags
+- Tags from approved list
+- See main standard `docs/templates/ADR.template.md` for template
+
+## Cross-Linking
+
+This project links to:
+
+**Dependencies:**
+- [@kb-labs/devkit](https://github.com/KirillBaranov/kb-labs-devkit) - DevKit presets
+
+**Used By:**
+- New KB Labs projects for scaffolding
+
+**Ecosystem:**
+- [KB Labs](https://github.com/KirillBaranov/kb-labs) - Main ecosystem repository
+
+---
+
+**Last Updated:** 2025-11-03  
+**Standard Version:** 1.0 (following KB Labs ecosystem standard)  
+**See Main Standard:** [KB Labs Documentation Standard](https://github.com/KirillBaranov/kb-labs/blob/main/docs/DOCUMENTATION.md)
+
+
+

package/docs/adr/0000-template.md

@@ -0,0 +1,49 @@
+# ADR-XXXX: [Brief Decision Title]
+
+**Date:** YYYY-MM-DD
+**Status:** Proposed | Accepted | Deprecated | Superseded
+**Deciders:** KB Labs Team
+**Last Reviewed:** YYYY-MM-DD
+**Reviewers:** [Optional list of reviewers]
+**Tags:** [tag1, tag2, tag3]
+
+> **Note:** Tags are mandatory. Minimum 1 tag, maximum 5 tags. See approved tags list in [DOCUMENTATION.md](../DOCUMENTATION.md#adr-tags).
+
+## Context
+
+_Describe the problem or situation that necessitated this decision._  
+_What alternatives were considered? What constraints exist?_
+
+## Decision
+
+_Describe the decision that was made. Key aspects: structure, tools, practices._  
+_Include diagrams or schemas if applicable._
+
+## Consequences
+
+### Positive
+
+- Benefits of the chosen solution
+
+### Negative
+
+- Drawbacks and risks
+
+### Alternatives Considered
+
+- Why other options were rejected
+
+## Implementation
+
+_What changes after this decision is made? What processes or code need to be updated?_  
+_Will this decision be revisited in the future?_
+
+## References
+
+- [Discussion / Pull Request](url)
+- [Related ADRs](./0000-other-decision.md)
+
+---
+
+**Last Updated:** YYYY-MM-DD  
+**Next Review:** YYYY-MM-DD (if scheduled)

package/docs/adr/0001-architecture-and-repository-layout.md

@@ -0,0 +1,33 @@
+# ADR-0001: Architecture and Repository Layout
+
+**Date:** 2025-09-13
+**Status:** Accepted
+**Deciders:** KB Labs Team
+**Last Reviewed:** 2025-11-03
+**Tags:** [architecture, tooling]
+
+## Context
+
+KB Labs products must be consistent across repositories. Each repository should follow the same monorepo-style layout to support apps, packages, and fixtures.
+
+## Decision
+
+- Use PNPM workspaces for package management
+- Repository root must contain:
+  - `/apps` — example/demo apps or product UI
+  - `/packages` — core logic, reusable libraries, domain modules
+  - `/fixtures` — sample diffs, test inputs, reference data
+  - `/docs` — ADRs, handbook, guides
+- Shared configs (tsconfig, eslint, prettier, vitest) live in root
+
+## Consequences
+
+**Positive:**
+
+- Consistent developer experience across products
+- Easy onboarding: all repositories look alike
+- Enables cross-product reuse of tools/scripts
+
+**Negative:**
+
+- Initial setup complexity for new repositories

package/docs/adr/0002-plugins-and-extensibility.md

@@ -0,0 +1,46 @@
+# ADR-0002: Plugins and Extensibility
+
+**Date:** 2025-09-13
+**Status:** Accepted
+**Deciders:** KB Labs Team
+**Last Reviewed:** 2025-11-03
+**Tags:** [architecture, api]
+
+## Context
+
+KB Labs products are designed to be reusable across different stacks, domains, and teams. To ensure long-term scalability, all products (AI Review, AI Docs, AI Tests, etc.) must support a flexible plugin & extension system. Without this, every new feature would require hardcoding into the core, increasing maintenance burden and reducing adaptability.
+
+## Decision
+
+- Each KB Labs product must expose a plugin API that allows third-party developers (or other KB Labs packages) to extend behavior without modifying the core
+- The plugin system must be:
+  1. **Isolated** — Plugins run in a sandboxed scope and cannot break the core
+  2. **Composable** — Multiple plugins can be combined in one pipeline
+  3. **Discoverable** — Plugins are registered via a central registry (`plugins/index.ts`) or a configuration file (`.kblabsrc.json`)
+  4. **Typed** — All plugin interfaces must be defined in `@kb-labs/core` using TypeScript types and Zod schemas
+  5. **Cross-product** — The same plugin (e.g., a Slack notifier) can be reused in AI Review, AI Docs, and AI Tests without rewriting
+
+## Examples
+
+- **AI Review** — rule providers, LLM strategies, custom output formatters
+- **AI Docs** — content generators, format exporters (Markdown, HTML, Confluence)
+- **AI Tests** — test strategy plugins, snapshot comparators
+- **Shared** — analytics/logging, secret providers, budget control
+
+## Consequences
+
+**Positive:**
+
+- Easier to onboard contributors: they extend via plugins instead of modifying the core
+- Ensures product consistency: every KB Labs product has the same extensibility model
+- Avoids long-term lock-in
+
+**Negative:**
+
+- Core complexity increases slightly
+- Additional abstraction layer to maintain
+
+## Alternatives Considered
+
+- **Hardcoded integrations** — rejected (not scalable, not reusable)
+- **Separate extension repositories** — rejected (too fragmented, harder to maintain)