@kb-labs/adapters 0.5.0

package/docs/adr/0003-package-and-module-boundaries.md

@@ -0,0 +1,37 @@
+# ADR-0003: Package and Module Boundaries
+
+**Date:** 2025-09-13
+**Status:** Accepted
+**Deciders:** KB Labs Team
+**Last Reviewed:** 2025-11-03
+**Tags:** [architecture, process]
+
+## Context
+
+Products in KB Labs often require multiple internal packages. Without strict boundaries, cross-dependencies can grow messy and unmaintainable.
+
+## Decision
+
+- Every package under `/packages` must define:
+  - `src/` — implementation
+  - `index.ts` — public entry point
+  - `types/` — exported types & schemas
+- Packages must only depend on public exports of other packages
+- Cross-package imports must use workspace aliases (`@kb-labs/<pkg>`)
+- Domain rules:
+  - Core logic in `@kb-labs/core`
+  - Product-specific code in `@kb-labs/<product>`
+  - Experimental code → feature packages, not core
+
+## Consequences
+
+**Positive:**
+
+- Prevents tight coupling
+- Core remains minimal and reusable
+- Easier to extract packages as standalone OSS later
+
+**Negative:**
+
+- Requires discipline to maintain boundaries
+- More complex dependency management

package/docs/adr/0004-versioning-and-release-policy.md

@@ -0,0 +1,38 @@
+# ADR-0004: Versioning and Release Policy
+
+**Date:** 2025-09-13
+**Status:** Accepted
+**Deciders:** KB Labs Team
+**Last Reviewed:** 2025-11-03
+**Tags:** [process, deployment]
+
+## Context
+
+The KB Labs ecosystem must stay consistent, while still allowing individual products to evolve.
+
+## Decision
+
+- Use Semantic Versioning (SemVer) for all published packages
+- Core (`@kb-labs/core`) follows stricter rules:
+  - **MAJOR:** breaking changes in APIs/schemas
+  - **MINOR:** new features, backward-compatible
+  - **PATCH:** bugfixes
+- Products (`ai-review`, `ai-docs`, `ai-tests`, etc.) can release independently, but must pin to compatible core versions
+- Changelog generation automated via changesets or `@kb-labs/changelog-generator`
+- Release flow:
+  1. Pull request → CI check (lint, type-check, test)
+  2. Merge → changeset entry created
+  3. Release pipeline tags version, publishes to npm, updates changelog
+
+## Consequences
+
+**Positive:**
+
+- Predictable updates across ecosystem
+- Users know when breaking changes occur
+- Easy adoption of multiple products without fear of hidden breakage
+
+**Negative:**
+
+- Requires careful coordination for major releases
+- More complex release automation setup

package/docs/adr/0005-use-devkit-for-shared-tooling.md

@@ -0,0 +1,48 @@
+# ADR-0005: Use DevKit for Shared Tooling
+
+**Date:** 2025-09-15
+**Status:** Accepted
+**Deciders:** KB Labs Team
+**Last Reviewed:** 2025-11-03
+**Tags:** [tooling, process]
+
+## Context
+
+The **kb-labs** ecosystem consists of multiple projects (core, cli, product-template, etc.).  
+Each project requires identical tooling configuration: ESLint, Prettier, Vitest, TSConfig, GitHub Actions, etc.
+
+If these configurations are stored separately in each repository:
+
+- Code and rule duplication occurs
+- Maintaining consistent style becomes difficult (changes need to be applied manually to all projects)
+- Risk of desynchronization increases (e.g., different versions of eslint-config or tsconfig)
+
+## Decision
+
+We are extracting all base configurations and actions into a separate package **@kb-labs/devkit**.  
+The project template (`kb-labs-product-template`) includes devkit, with local configs serving only as "thin wrappers" over it.
+
+This approach provides:
+
+- Centralized logic and rules in `kb-labs-devkit`
+- Fastest possible new project creation (setup through template and devkit)
+- Single-point maintenance for rule/infrastructure changes that apply to all projects
+
+## Consequences
+
+### Positive
+
+- Consistent code style and testing across all repositories
+- Minimal boilerplate in new projects
+- Simplified maintenance and updates
+
+### Negative
+
+- Dependency on `@kb-labs/devkit` (projects cannot build without it)
+- DevKit bugs or errors affect all projects simultaneously
+- Requires discipline when updating DevKit versions across all dependent projects
+
+## Alternatives Considered
+
+- **Keep configs within each project** — Rejected due to high maintenance cost
+- **Use external shared configs** (e.g., `eslint-config-standard`) without custom devkit — Rejected as more custom rules and integrations (tsup, GitHub Actions) are required

package/docs/adr/0006-adopt-devkit-sync.md

@@ -0,0 +1,47 @@
+# ADR-0006: Adopt DevKit Synchronization
+
+**Date:** 2025-09-18
+**Status:** Accepted
+**Deciders:** KB Labs Team
+**Last Reviewed:** 2025-11-03
+**Tags:** [tooling, process]
+
+## Context
+
+This template inherits shared tooling from `@kb-labs/devkit`: ESLint/Prettier/Vitest/Tsup/TS presets, reusable CI, and preconfigured Cursor agents. Without a clear sync mechanism, templates and products could diverge from the central standards.
+
+## Decision
+
+The template **adopts DevKit synchronization**:
+
+- Tooling configs are **thin wrappers** over DevKit exports (no local forks)
+- Cursor agents (`/agents`, `.cursorrules`, `AGENTS.md`) are synchronized from DevKit via:
+  ```bash
+  pnpm agents:sync
+  ```
+- Before major contributions and releases, run the sync to ensure alignment
+
+## Consequences
+
+**Positive:**
+
+- Guarantees consistency with KB Labs standards
+- Reduces setup time for new products
+- Keeps docs and agents up-to-date without manual copy/paste
+- Minimal boilerplate
+- Centralized updates; predictable upgrades
+
+**Negative:**
+
+- Requires DevKit availability and version pinning
+- Local deviations must be explicitly justified (and usually upstreamed to DevKit)
+
+## Implementation
+
+- `eslint.config.js`, `vitest.config.ts`, `tsconfig.base.json` extend/import DevKit presets
+- `pnpm agents:sync` copies the latest agent definitions
+- CI reuses DevKit workflows via `uses: KirillBaranov/kb-labs-devkit/.github/workflows/...@main` (or versioned tags later)
+
+## References
+
+- DevKit ADR: `@kb-labs/devkit/docs/adr/0001-repo-synchronization-via-devkit.md`

package/docs/adr/0007-drift-kit-check.md

@@ -0,0 +1,72 @@
+# ADR-0007: DevKit Drift Check
+
+**Date:** 2025-09-18
+**Status:** Proposed
+**Deciders:** KB Labs Team
+**Last Reviewed:** 2025-11-03
+**Tags:** [tooling, process]
+
+## Context
+
+As our development kits (DevKits) evolve, it is essential to ensure consistency and detect any unintended changes or drifts from the expected configuration or state. Drift in DevKits can lead to integration issues, unexpected behaviors, and increased debugging time. To maintain quality and reliability, we need a standardized approach to check for drift in our DevKits.
+
+## Decision
+
+We will implement a DevKit Drift Check process that involves:
+
+- Defining a baseline configuration and state for each DevKit version
+- Automating the comparison of the current DevKit state against the baseline
+- Reporting any deviations or drifts clearly and promptly
+- Integrating the drift check into our continuous integration (CI) pipeline to catch issues early
+- Providing remediation steps or automated fixes when feasible
+
+This approach ensures that any drift is detected early, maintaining the integrity and reliability of our DevKits.
+
+## Implementation
+
+The drift check is implemented via a script located at `scripts/devkit-sync.mjs`. This script facilitates two main commands:
+
+- `pnpm sync`: Synchronizes the project configuration files with the baseline sources provided by the `@kb-labs/devkit` package
+- `pnpm drift-check`: Verifies the consistency of the project files against the baseline. It compares the current project files against the source files in `@kb-labs/devkit`, reports any differences found, and exits with code 2 if any drift is detected
+
+When drift is detected, the script outputs a detailed log showing the files that differ and the specific discrepancies, enabling developers to quickly identify and address the issues.
+
+Example output when drift is detected:
+
+```bash
+Drift detected in the following files:
+ - config/devkit.json
+ - scripts/build.js
+
+Differences:
+--- baseline/config/devkit.json
++++ project/config/devkit.json
+@@ -1,5 +1,5 @@
+ {
+-  "version": "1.0.0",
++  "version": "1.0.1",
+   "features": ["featureA", "featureB"]
+ }
+
+--- baseline/scripts/build.js
++++ project/scripts/build.js
+@@ -10,7 +10,7 @@
+-    console.log("Build started");
++    console.log("Build initiated");
+```
+
+This mechanism ensures that any unintended changes are caught early, preserving the integrity of the DevKit environment.
+
+## Consequences
+
+**Positive:**
+
+- Increased confidence in DevKit consistency
+- Early detection of configuration or state issues
+- Automated validation reduces manual verification overhead
+
+**Negative:**
+
+- Additional CI pipeline steps and maintenance overhead
+- Need to maintain baseline definitions as DevKits evolve
+- Dependency on DevKit availability for drift checks

package/docs/adr/0008-devkit-sync-wrapper-strategy.md

@@ -0,0 +1,67 @@
+# ADR-0008: DevKit Sync Wrapper Strategy in Product Template
+
+**Date:** 2025-09-25
+**Status:** Accepted
+**Deciders:** KB Labs Team
+**Last Reviewed:** 2025-11-03
+**Tags:** [tooling, process]
+
+## Context
+
+For proper operation of projects created from @kb-labs/product-template, synchronization of certain artifacts from @kb-labs/devkit is required (e.g., agents, .cursorrules, VS Code settings).
+
+Previously, it was assumed to use the kb-devkit-sync binary directly or call a local script from devkit, but this approach complicated migrations and required additional configuration.
+
+The main goal is to minimize friction when starting a new project and ensure stability of the synchronization mechanism regardless of the developer environment.
+
+## Decision
+
+Wrapper npm scripts will be added to the product-template:
+
+```json
+"scripts": {
+  "devkit:sync": "kb-devkit-sync",
+  "devkit:check": "kb-devkit-sync --check",
+  "postinstall": "pnpm -s devkit:sync || true"
+}
+```
+
+This approach provides:
+- Calls are made through package.json without the need to manually install the binary
+- postinstall automatically pulls artifacts when installing dependencies
+- devkit:check allows running drift checks in CI
+
+## Consequences
+
+### Positive
+
+- **Simplicity**: Users run `pnpm devkit:sync` without knowledge of internal implementation
+- **Automation**: Synchronization happens on every `pnpm install`
+- **Error reduction**: Single approach for all projects created from the template
+
+### Negative
+
+- **Hard dependency**: Tight coupling to the presence of kb-devkit-sync binary in @kb-labs/devkit
+- **Migration risk**: If the binary is renamed or API changes, all template-based projects will need updates
+
+### Alternatives Considered
+
+- **Local script in each project** (bin/devkit-sync.mjs): More control but requires duplication and manual maintenance
+- **Direct devkit API calls**: More complex for consumers, increases risk of configuration drift
+- **No automatic sync**: Consumers would have to manually copy files → too high cost of errors
+
+## Implementation
+
+- The described scripts have been added to the template's package.json
+- postinstall ensures auto-synchronization after dependency installation
+- CI pipelines will use `pnpm devkit:check` for drift verification
+
+Future steps:
+- If an alternative implementation emerges (e.g., REST API or new CLI utility), an ADR-supersede can be created
+- Sync logic will be documented in the template's README for new users
+
+## References
+
+- [DevKit Repository](https://github.com/kb-labs/devkit) <!-- TODO: Replace with actual URL -->
+- [Product Template Repository](https://github.com/kb-labs/product-template) <!-- TODO: Replace with actual URL -->
+- [Related ADR: ADR-0005: Use DevKit for Shared Tooling](./0005-use-devkit-for-shared-tooling.md)

package/docs/naming-convention.md

@@ -0,0 +1,272 @@
+# Naming Convention: The Pyramid Rule
+
+**Status:** Mandatory
+**Applies to:** All packages in KB Labs ecosystem
+**Date:** 2025-11-30
+
+---
+
+## The Pyramid Rule
+
+All packages in the KB Labs ecosystem follow a strict naming convention called **"The Pyramid Rule"**:
+
+```
+@kb-labs/{repo}-{package}
+```
+
+Where:
+- `{repo}` - the monorepo name (e.g., `core`, `cli`, `shared`, `plugin`)
+- `{package}` - the package name within that repo
+
+**Critical:** The folder name MUST ALWAYS match `{repo}-{package}`.
+
+---
+
+## The Pyramid Structure
+
+```
+     @kb-labs              ← Base namespace (all packages)
+        ↓
+     {repo}                ← Repository name (core, cli, shared, plugin)
+        ↓
+    {package}              ← Package name
+```
+
+**Example:**
+```
+Repository:  kb-labs-core
+Package:     config
+Result:      @kb-labs/core-config
+Folder:      kb-labs-core/packages/core-config/
+```
+
+---
+
+## Rules
+
+### ✅ DO
+
+**1. Always use the repo prefix in folder names:**
+```
+kb-labs-core/packages/core-config/      → @kb-labs/core-config ✅
+kb-labs-cli/packages/cli-core/          → @kb-labs/cli-core ✅
+kb-labs-shared/packages/shared-diff/    → @kb-labs/shared-diff ✅
+```
+
+**2. Keep folder name and package name in sync:**
+```json
+// In kb-labs-core/packages/core-config/package.json
+{
+  "name": "@kb-labs/core-config"  // Matches folder: core-config
+}
+```
+
+**3. Use descriptive package names:**
+```
+core-state-broker      ✅  (clear what it does)
+core-framework         ✅  (indicates it's infrastructure)
+core-cli               ✅  (CLI commands for core)
+```
+
+### ❌ DON'T
+
+**1. Skip the repo prefix:**
+```
+kb-labs-core/packages/config/           → @kb-labs/core-config ❌
+kb-labs-core/packages/sys/              → @kb-labs/core-sys ❌
+```
+**Problem:** Folder name doesn't match package name pattern.
+
+**2. Use inconsistent naming:**
+```
+kb-labs-core/packages/cli-core/         → @kb-labs/core-cli ❌
+```
+**Problem:** Folder is `cli-core` but package is `core-cli` (inverted).
+
+**3. Create packages without repo prefix:**
+```
+kb-labs-core/packages/bundle/           → @kb-labs/bundle ❌
+```
+**Problem:** Missing `core-` prefix in both folder and package name.
+
+---
+
+## Examples by Repository
+
+### kb-labs-core
+
+All packages MUST have `core-` prefix:
+
+```
+✅ core-bundle/         → @kb-labs/core-bundle
+✅ core-cli/            → @kb-labs/core-cli
+✅ core-config/         → @kb-labs/core-config
+✅ core-framework/      → @kb-labs/core-framework
+✅ core-state-broker/   → @kb-labs/core-state-broker
+✅ core-sys/            → @kb-labs/core-sys
+✅ core-types/          → @kb-labs/core-types
+```
+
+### kb-labs-cli
+
+All packages MUST have `cli-` prefix:
+
+```
+✅ cli-api/             → @kb-labs/cli-api
+✅ cli-commands/        → @kb-labs/cli-commands
+✅ cli-contracts/       → @kb-labs/cli-contracts
+✅ cli-core/            → @kb-labs/cli-core
+✅ cli-runtime/         → @kb-labs/cli-runtime
+```
+
+### kb-labs-shared
+
+All packages MUST have `shared-` prefix:
+
+```
+✅ shared-command-kit/  → @kb-labs/shared-command-kit
+✅ shared-cli-ui/       → @kb-labs/shared-cli-ui
+✅ shared-diff/         → @kb-labs/shared-diff
+✅ shared-repo/         → @kb-labs/shared-repo
+```
+
+### kb-labs-plugin
+
+All packages MUST have `plugin-` prefix:
+
+```
+✅ plugin-manifest/     → @kb-labs/plugin-manifest
+✅ plugin-runtime/      → @kb-labs/plugin-runtime
+✅ plugin-adapter-cli/  → @kb-labs/plugin-adapter-cli
+```
+
+---
+
+## Special Cases
+
+### Multi-word package names
+
+Use kebab-case for multi-word names:
+
+```
+✅ core-state-broker/       → @kb-labs/core-state-broker
+✅ core-cli-adapters/       → @kb-labs/core-cli-adapters
+✅ plugin-adapter-rest/     → @kb-labs/plugin-adapter-rest
+```
+
+### Adapters and sub-packages
+
+Adapters can be nested but still follow the rule:
+
+```
+✅ kb-labs-plugin/packages/plugin-adapter-cli/
+✅ kb-labs-plugin/packages/plugin-adapter-rest/
+✅ kb-labs-core/packages/core-cli-adapters/
+```
+
+---
+
+## Migration Checklist
+
+When creating a new package or fixing naming violations:
+
+- [ ] Folder name follows `{repo}-{package}` pattern
+- [ ] `package.json` name matches `@kb-labs/{repo}-{package}`
+- [ ] Folder name and package name are in sync
+- [ ] All `link:` dependencies updated to new paths
+- [ ] All `workspace:*` dependencies updated to new names
+- [ ] Documentation updated (README, imports)
+- [ ] `pnpm install` runs without errors
+
+---
+
+## Validation
+
+### Check for violations
+
+```bash
+# List all packages and check naming
+find kb-labs-*/packages -name package.json -exec grep -H '"name":' {} \;
+
+# Expected pattern: kb-labs-{repo}/packages/{repo}-{package}/package.json
+```
+
+### Common violations
+
+1. **Missing repo prefix in folder:**
+   ```
+   kb-labs-core/packages/config/  ❌
+   Should be: core-config/
+   ```
+
+2. **Inverted naming:**
+   ```
+   kb-labs-core/packages/cli-core/ with @kb-labs/core-cli  ❌
+   Should be: core-cli/ or rename package
+   ```
+
+3. **Missing repo prefix in package name:**
+   ```
+   "name": "@kb-labs/sandbox"  ❌
+   Should be: "@kb-labs/core-sandbox"
+   ```
+
+---
+
+## Benefits
+
+### 1. Zero Ambiguity
+- No confusion about where a package belongs
+- `@kb-labs/core-config` → clearly in `kb-labs-core`
+- `@kb-labs/cli-core` → clearly in `kb-labs-cli`
+
+### 2. Easy Navigation
+- Folder structure mirrors package names
+- `import from '@kb-labs/core-sys'` → look in `kb-labs-core/packages/core-sys/`
+
+### 3. Prevents Collisions
+- Before: two packages could have `@kb-labs/core-cli` (collision!)
+- After: impossible - repo prefix enforces uniqueness
+
+### 4. Scalability
+- New repos automatically follow pattern
+- `kb-labs-ai/packages/ai-docs/` → `@kb-labs/ai-docs`
+
+---
+
+## History
+
+**Before (Problematic):**
+```
+kb-labs-core/packages/sys/              → @kb-labs/core-sys
+kb-labs-core/packages/cli/              → @kb-labs/core-cli
+kb-labs-core/packages/cli-core/         → @kb-labs/core-cli  ← COLLISION!
+kb-labs-cli/packages/core/              → @kb-labs/cli-core
+kb-labs-cli/packages/cli-core/          → @kb-labs/cli-core  ← WRAPPER
+```
+
+**After (Clean):**
+```
+kb-labs-core/packages/core-sys/         → @kb-labs/core-sys
+kb-labs-core/packages/core-cli/         → @kb-labs/core-cli
+kb-labs-core/packages/core-framework/   → @kb-labs/core-framework
+kb-labs-cli/packages/cli-core/          → @kb-labs/cli-core
+```
+
+**Changes made (2025-11-30):**
+- Renamed 13 packages in `kb-labs-core`
+- Renamed 1 package in `kb-labs-cli`
+- Moved `command-kit` to `kb-labs-shared`
+- Eliminated name collision between framework and CLI commands
+- Updated 50+ dependency references
+
+---
+
+## See Also
+
+- [Documentation Guide](./DOCUMENTATION.md) - How to document your product
+- [ADRs](./adr/) - Architecture Decision Records
+
+---
+
+**Questions?** Check with the team or open an issue if the naming convention is unclear.

package/eslint.config.js

@@ -0,0 +1,27 @@
+/**
+ * Standard ESLint configuration template
+ *
+ * This is the canonical template for all @kb-labs packages.
+ * DO NOT modify this file locally - it is synced from @kb-labs/devkit
+ *
+ * Customization guidelines:
+ * - DevKit preset already includes all standard ignores
+ * - Only add project-specific ignores if absolutely necessary
+ * - Document why custom ignores are needed
+ *
+ * @see https://github.com/kb-labs/devkit#eslint-configuration
+ */
+import nodePreset from '@kb-labs/devkit/eslint/node.js';
+
+export default [
+  ...nodePreset,
+
+  // OPTIONAL: Add project-specific ignores only if needed
+  // DevKit preset already ignores: dist/, coverage/, node_modules/, *.d.ts, scripts/, etc.
+  // {
+  //   ignores: [
+  //     // Add ONLY project-specific patterns here
+  //     // Example: '**/*.generated.ts',
+  //   ]
+  // }
+];

package/kb-labs.config.json

@@ -0,0 +1,5 @@
+{
+  "sync": {
+    "enabled": true
+  }
+}