@kb-labs/adapters 0.5.0

package/.cursorrules

@@ -0,0 +1,32 @@
+# Global Cursor rules for KB Labs projects
+allow:
+  - read: "src/**/*"
+  - read: "packages/**/*"
+  - read: "apps/**/*"
+  - read: "docs/**/*"
+  - read: "README.md"
+  - read: "package.json"
+  - read: "tsconfig*.json"
+  - read: ".github/**/*"
+  - read: ".cursorrules"
+  - read: "agents/**/*"
+  - write: "src/**/*"
+  - write: "packages/**/*"
+  - write: "apps/**/*"
+  - write: "docs/**/*"
+  - write: "README.md"
+  - write: "CONTRIBUTING.md"
+  - write: "AGENTS.md"
+  - write: "docs/adr/**/*"
+  - run: "pnpm *"
+  - run: "git *"
+deny:
+  - write: "node_modules/**/*"
+  - write: "dist/**/*"
+  - write: "coverage/**/*"
+  - write: ".yalc/**/*"
+  - run: "rm -rf *"
+notes:
+  - Always prefer presets from @kb-labs/devkit (tsconfig/eslint/prettier/vitest/tsup).
+  - Keep local configs as thin wrappers (import/extends from devkit).
+  - Respect package.json "exports" (no deep imports).

package/.github/workflows/ci.yml

@@ -0,0 +1,13 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch: {}
+
+jobs:
+  call:
+    uses: KirillBaranov/kb-labs-devkit/.github/workflows/ci-reusable.yml@main
+    with:
+      node-version: '20'
+      run-coverage: true

package/.github/workflows/deploy.yml

@@ -0,0 +1,28 @@
+name: Deploy
+
+# Deploys all services to VPS via docker compose
+# Triggered manually with a specific image tag
+#
+# Prerequisites:
+#   Add secrets in GitHub → Settings → Secrets → Actions:
+#     VPS_HOST     - server IP or hostname
+#     VPS_USER     - SSH username (e.g. deploy)
+#     VPS_SSH_KEY  - SSH private key
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Image tag to deploy (e.g. release-1.0.0)
+        required: true
+        type: string
+
+jobs:
+  call:
+    uses: KirillBaranov/kb-labs-devkit/.github/workflows/deploy-reusable.yml@main
+    with:
+      image-tag: ${{ inputs.tag }}
+      compose-file: docker-compose.production.yml
+      deploy-dir: /opt/kb-labs
+      health-check-url: http://localhost:5050/api/v1/health
+    secrets: inherit

package/.github/workflows/docker-build.yml

@@ -0,0 +1,25 @@
+name: Docker Build
+
+# Builds and pushes Docker image to ghcr.io
+#
+# Flow:
+#   rc branch   → build image tagged rc-<sha> (for testing)
+#   release tag → build image tagged release-x.y.z + latest (for deploy)
+#
+# Configure:
+#   - Set image-name to your service name (e.g. kb-labs-rest-api)
+#   - Set dockerfile path if not at repo root
+
+on:
+  push:
+    branches: [rc]
+    tags: ['release-*']
+  workflow_dispatch: {}
+
+jobs:
+  call:
+    uses: KirillBaranov/kb-labs-devkit/.github/workflows/docker-build-reusable.yml@main
+    with:
+      image-name: kb-labs-my-service  # TODO: change to your service name
+      dockerfile: Dockerfile
+      context: .

package/.github/workflows/drift-check.yml

@@ -0,0 +1,10 @@
+name: Drift Check
+on:
+  workflow_dispatch: {}
+  schedule:
+    - cron: '0 3 * * *' # nightly
+jobs:
+  drift:
+    uses: KirillBaranov/kb-labs-devkit/.github/workflows/drift-check-reusable.yml@main
+    with:
+      node-version: '20'

package/.github/workflows/profiles-validate.yml

@@ -0,0 +1,16 @@
+name: Profiles Validate
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch: {}
+
+jobs:
+  call:
+    uses: KirillBaranov/kb-labs-devkit/.github/workflows/profiles-validate-reusable.yml@main
+    with:
+      node_version: '20'
+      soft_fail: true
+      working_directory: '.'
+      fixtures_dir: ''
+      log_level: 'info'

package/.github/workflows/release.yml

@@ -0,0 +1,8 @@
+name: Release
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch: {}
+jobs:
+  call:
+    uses: KirillBaranov/kb-labs-devkit/.github/workflows/release-reusable.yml@main

package/.kb/devkit/agents/devkit-maintainer/context.globs

@@ -0,0 +1,15 @@
+src/**/*
+packages/**/*
+apps/**/*
+docs/**/*
+.eslintrc.*
+eslint.config.*
+vitest.config.*
+tsconfig*.json
+.prettierrc*
+.editorconfig
+package.json
+.github/**/*
+README.md
+CONTRIBUTING.md
+AGENTS.md

package/.kb/devkit/agents/devkit-maintainer/permissions.yml

@@ -0,0 +1,17 @@
+permissions:
+  file:
+    read: ["**/*"]
+    write:
+      - "eslint.config.js"
+      - "vitest.config.*"
+      - "tsconfig*.json"
+      - ".prettierrc*"
+      - ".editorconfig"
+      - "package.json"
+      - ".github/workflows/*.yml"
+      - "README.md"
+      - "CONTRIBUTING.md"
+  terminal:
+    allowed: ["pnpm *", "git *"]
+  git:
+    allowed: ["add", "commit", "restore", "checkout", "switch"]

package/.kb/devkit/agents/devkit-maintainer/prompt.md

@@ -0,0 +1,28 @@
+# DevKit Maintainer (KB Labs)
+
+You maintain adoption of the KB Labs DevKit across repositories.
+
+**Goals**
+- Enforce using `@kb-labs/devkit` for tsconfig, ESLint, Prettier, Vitest, and Tsup.
+- Ensure CI uses reusable workflows from `kb-labs-devkit`.
+- Keep local configs as thin wrappers that import/extend DevKit presets.
+- Avoid breaking changes. Propose minimal diffs first.
+
+**Process**
+1) Audit repository for drift:
+   - Duplicate configs instead of devkit presets.
+   - Outdated scripts not using devkit.
+   - CI not using reusable workflows.
+2) Propose a patch plan (list files and diffs).
+3) Apply safe changes incrementally.
+4) Verify with `pnpm lint && pnpm type-check && pnpm -r run test && pnpm -r run build`.
+
+**Rules**
+- Do not modify domain/business logic.
+- Keep changes minimal and reversible.
+- Prefer project-wide consistency over ad-hoc fixes.
+
+**Outputs**
+- Patch plan (bulleted).
+- Diffs for files to change.
+- A short validation checklist to run locally and in CI.

package/.kb/devkit/agents/devkit-maintainer/runbook.md

@@ -0,0 +1,31 @@
+# Runbook — DevKit Maintainer
+
+## Audit
+- Check for:
+  - Local ESLint/TS/Prettier/Vitest/Tsup configs not referencing devkit.
+  - package.json scripts that don't use devkit presets.
+  - CI not using `KirillBaranov/kb-labs-devkit/.github/workflows/ci.yml@v1` (or @main).
+  - Misaligned tsconfig (`inlineSources`, missing `resolveJsonModule`, etc.).
+
+## Patch Plan (example)
+1. Replace local `eslint.config.js` with:
+   ```js
+   import config from '@kb-labs/devkit/eslint/node.js'
+   export default config
+   ```
+
+2. Replace tsconfig.json to extend from project base, which extends devkit.
+3. Update scripts to use devkit presets:
+   - build/dev with tsup preset, or local tsup config if entry differs.
+   - vitest config centralized: vitest -c ../../vitest.config.ts for packages.
+4. CI: use reusable workflow from devkit.
+
+## Validate
+- pnpm install
+- pnpm lint && pnpm type-check
+- pnpm -r run test
+- pnpm -r run build
+
+## Notes
+- Prefer root vitest config (avoid TS configs under pure ESM).
+- Avoid deep imports; ensure "exports" are respected.

package/.kb/devkit/agents/docs-crafter/prompt.md

@@ -0,0 +1,24 @@
+# Docs Drafter (KB Labs)
+
+You draft and maintain developer-facing documentation.
+
+**Goals**
+- Generate or update: README.md, CONTRIBUTING.md, and ADRs in `docs/adr/`.
+- Keep docs concise, actionable, and aligned with DevKit conventions.
+- Link to ADRs from README when architectural decisions are relevant.
+
+**Process**
+1) Inspect repo structure, scripts, and DevKit integration.
+2) Propose doc outline or diffs (show what will change).
+3) Write/update docs incrementally; keep tone consistent.
+4) Validate commands actually work (`pnpm` scripts).
+
+**Rules**
+- No boilerplate walls of text; focus on “how to run, build, test, release”.
+- Use the ADR template when a decision affects architecture/tooling.
+- Cross-link related docs (ADR <-> README <-> CONTRIBUTING).
+
+**Outputs**
+- Updated README.md with Quickstart and scripts.
+- CONTRIBUTING.md with lint/test/build instructions, ADR policy.
+- New ADRs using `docs/adr/0000-template.md`.

package/.kb/devkit/agents/docs-crafter/runbook.md

@@ -0,0 +1,18 @@
+# Runbook — Docs Drafter
+
+## Minimum README sections
+- What is this package/app.
+- Quickstart: install, build, dev.
+- Scripts (lint/test/type-check/build).
+- DevKit integration and CI note.
+- Links to ADRs.
+
+## CONTRIBUTING essentials
+- Node/pnpm versions.
+- Lint/test/build commands.
+- ADR policy: when to add a new record; link to template.
+
+## ADR
+- Use `docs/adr/0000-template.md`.
+- Record decisions affecting architecture/tooling.
+- Cross-link from README.

package/.kb/devkit/agents/release-manager/context.globs

@@ -0,0 +1,7 @@
+packages/**/*
+apps/**/*
+CHANGELOG.md
+README.md
+package.json
+pnpm-lock.yaml
+.github/workflows/*

package/.kb/devkit/agents/release-manager/prompt.md

@@ -0,0 +1,27 @@
+# Release Manager (KB Labs)
+
+You prepare safe releases.
+
+**Goals**
+- Draft a release plan: version bump, summary, and changelog.
+- Verify build and tests before proposing a release.
+- Use GitHub Releases; npm publish only when explicitly requested and configured.
+
+**Process**
+1) Analyze commits and changes since last tag.
+2) Recommend semver bump (patch/minor/major).
+3) Run validation locally:
+   - `pnpm -r run build`
+   - `pnpm -r run test` (or `--if-present`)
+4) Prepare release notes (features/fixes/breaking).
+5) Output a checklist with exact commands/steps.
+
+**Rules**
+- Do not push tags or publish without confirmation.
+- Respect monorepo workspaces; note any packages impacted.
+- If publishing to npm, require `NPM_TOKEN` and proper access.
+
+**Outputs**
+- Release plan (version, notes, affected packages).
+- GitHub Release draft text.
+- Optional `changeset` if used (or plain changelog).

package/.kb/devkit/agents/release-manager/runbook.md

@@ -0,0 +1,17 @@
+# Runbook — Release Manager
+
+## Preflight
+- `pnpm install`
+- `pnpm lint && pnpm type-check`
+- `pnpm -r run test`
+- `pnpm -r run build`
+
+## Plan
+- Determine semver bump.
+- Summarize changes by category.
+- Identify impacted packages (monorepo).
+
+## Output
+- GitHub Release draft (markdown).
+- Optional: `pnpm -r publish` if configured (requires `NPM_TOKEN`).
+- Do not push tags unless confirmed.

package/.kb/devkit/agents/test-generator/context.globs

@@ -0,0 +1,7 @@
+src/**/*
+packages/**/*
+apps/**/*
+tsconfig*.json
+vitest.config.*
+package.json
+README.md

package/.kb/devkit/agents/test-generator/prompt.md

@@ -0,0 +1,27 @@
+# Test Generator (KB Labs)
+
+You generate pragmatic unit tests and improve coverage without brittleness.
+
+**Goals**
+- Co-located tests: `__tests__/*.spec.ts` or `*.test.ts`.
+- Use Vitest. Respect project’s exports (no deep imports).
+- Aim for ≥95% coverage where meaningful; avoid flaky or snapshot-heavy tests.
+- Cover branches, edge cases, and error paths.
+
+**Process**
+1) Scan source files and existing tests.
+2) Propose a coverage plan (file-by-file).
+3) Implement tests incrementally; run locally:
+   - `pnpm -r run test` (or per package)
+   - `pnpm -r run test:coverage` if configured
+4) Refine to remove redundancy and flakiness.
+
+**Rules**
+- Keep tests deterministic and fast.
+- Don’t introduce new runtime deps without confirmation.
+- Prefer simple assertions, explicit inputs, and clear setup/teardown.
+
+**Outputs**
+- Coverage plan with target %.
+- New/updated test files.
+- Short notes on what is intentionally left untested (if any).

package/.kb/devkit/agents/test-generator/runbook.md

@@ -0,0 +1,18 @@
+# Runbook — Test Generator
+
+## Steps
+1. Identify functions/methods with low/no coverage.
+2. For each function:
+   - Test main path, edge cases, and error handling.
+   - Avoid snapshots unless structure is stable and justified.
+3. Create tests in `__tests__/name.spec.ts` near the source file.
+4. Run tests and check coverage locally.
+
+## Commands
+- `pnpm -r run test`
+- `pnpm -r run test:coverage`
+- `pnpm --filter <pkg> run test`
+
+## Tips
+- Import from package public exports when possible to mirror user usage.
+- If a package has no tests, add a `smoke.spec.ts`.

package/CONTRIBUTING.md

@@ -0,0 +1,90 @@
+# Contributing Guide
+
+Thanks for considering a contribution to **KB Labs** projects!
+
+---
+
+## Development setup
+
+```bash
+pnpm i
+pnpm dev
+```
+
+## 📋 Development Guidelines
+
+### Code Style
+
+- **Coding style**: Follow ESLint + Prettier rules. Run `pnpm lint` before pushing.
+- **TypeScript**: Use strict mode and proper type annotations.
+- **Testing**: Cover all changes with Vitest. Run `pnpm test`.
+- **Documentation**: Document all public APIs and complex logic.
+
+### Commit Messages
+
+Use conventional commit format:
+
+```
+feat: add new feature
+fix: correct bug
+docs: update documentation
+refactor: restructure code
+test: add or update tests
+chore: maintenance tasks
+```
+
+### Architecture Decisions
+
+- For significant architectural changes, add an ADR in `docs/adr/`
+- Follow the ADR template in `docs/adr/0000-template.md`
+- Include required metadata (Date, Status, Deciders, **Last Reviewed**, **Tags**)
+- **Last Reviewed** date is required and should be updated periodically
+- **Tags** are mandatory (minimum 1, maximum 5 tags from approved list)
+- See [Documentation Standard](./docs/DOCUMENTATION.md) for ADR format requirements
+
+## DevKit Integration
+
+This project uses `@kb-labs/devkit` for shared tooling configurations. Key points:
+
+- **Configurations**: ESLint, Prettier, Vitest, TypeScript, and GitHub Actions are managed by devkit
+- **Local configs**: Act as thin wrappers over devkit configurations
+- **Updates**: When devkit is updated, run `pnpm install` to get the latest configurations
+- **Customization**: For project-specific rules, extend devkit configs rather than overriding them
+
+### DevKit Commands
+
+- `pnpm devkit:sync` - Sync DevKit configurations (runs automatically on install)
+- `pnpm devkit:check` - Check if sync is needed
+- `pnpm devkit:force` - Force sync (overwrites existing configs)
+- `pnpm devkit:help` - Show help and available options
+
+For more details, see [ADR-0005: Use DevKit for Shared Tooling](docs/adr/0005-use-devkit-for-shared-tooling.md).
+
+---
+
+## 🔄 Pull Request Process
+
+### Before Submitting
+
+1. **Fork** the repository and create a feature branch
+2. **Make your changes** following the guidelines above
+3. **Test thoroughly**:
+   ```bash
+   pnpm check  # Runs lint + type-check + tests
+   ```
+4. **Update documentation** if needed (README, API docs, ADRs)
+5. **Submit a PR** with:
+   - Clear description of changes
+   - Reference any related issues
+   - Ensure all CI checks pass
+
+### PR Requirements
+
+- Clear, descriptive title and description
+- Reference any related issues
+- Ensure all CI checks pass
+- Request review from maintainers
+
+---
+
+**See [Documentation Standard](./docs/DOCUMENTATION.md) for complete documentation guidelines.**