@kb-labs/shared 1.1.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/.vscode/settings.json

@@ -0,0 +1,23 @@
+{
+  "editor.tabSize": 2,
+  "editor.insertSpaces": true,
+  "editor.formatOnSave": true,
+  "files.eol": "\n",
+  // ESLint (flat config)
+  "eslint.useFlatConfig": true,
+  "eslint.experimental.useFlatConfig": true,
+  "eslint.validate": [
+    "javascript",
+    "javascriptreact",
+    "typescript",
+    "typescriptreact",
+    "vue"
+  ],
+  // Prettier
+  "prettier.requireConfig": true,
+  // TypeScript: использовать локальную версию в репозитории
+  "typescript.tsdk": "node_modules/typescript/lib",
+  // Vitest
+  "vitest.enable": true,
+  "vitest.disableWorkspaceWarning": true
+}

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog — @kb-labs/shared
+
+## 1.0.0 — 2026-02-24
+
+First stable release. Prior history represents internal R&D — this is the first versioned public release.
+
+### Packages
+
+| Package | Version |
+|---------|---------|
+| `@kb-labs/shared-cli-ui` | 1.0.0 |
+| `@kb-labs/shared-command-kit` | 1.0.0 |
+| `@kb-labs/shared-testing` | 1.0.0 |
+| `@kb-labs/shared-tool-kit` | 1.0.0 |
+| `@kb-labs/perm-presets` | 1.0.0 |
+
+### What's included
+
+**`@kb-labs/shared-cli-ui`** — CLI presentation layer: color utilities, progress bars, table rendering, debug output, sidebar layout. Used by all CLI commands for consistent visual output.
+
+**`@kb-labs/shared-command-kit`** — High-level command building utilities: flag helpers, analytics integration, error formatting, LLM helpers, `useConfig`, `useLogger`, `useStorage` hooks. Reduces boilerplate in command handlers.
+
+**`@kb-labs/perm-presets`** — Composable permission preset definitions and factories for plugin permission declarations. Used in plugin manifests to declare required platform access.
+
+**`@kb-labs/shared-testing`** — Test utilities for plugin development: mock platform builders, test context factories, sandbox setup helpers.
+
+**`@kb-labs/shared-tool-kit`** — Tool factory and mock utilities for agent tool development.
+
+### Notes
+
+- `shared-cli-ui` and `shared-command-kit` are the primary shared dependencies for all KB Labs plugins
+- `shared-testing` is a dev dependency — not included in production builds
+- `perm-presets` is the canonical way to declare plugin permissions in manifests

package/CONTRIBUTING.md

@@ -0,0 +1,117 @@
+# Contributing Guide
+
+Thanks for considering a contribution to **KB Labs Shared**!  
+This guide will help you get started with contributing to our shared utilities and libraries.
+
+## 🚀 Development Setup
+
+### Prerequisites
+
+- **Node.js:** >= 18.18.0
+- **pnpm:** >= 9.0.0
+
+### Initial Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/kirill-baranov/kb-labs-shared.git
+cd kb-labs-shared
+
+# Install dependencies
+pnpm install
+
+# Start development mode
+pnpm dev
+```
+
+## 📋 Development Guidelines
+
+### Code Style
+
+- Follow **ESLint** and **Prettier** rules configured in the project
+- Use **TypeScript strict mode** for all new code
+- Run `pnpm lint` before committing changes
+- Use `pnpm lint:fix` to automatically fix formatting issues
+
+### Testing
+
+- Write tests for all new functionality using **Vitest**
+- Maintain or improve test coverage
+- Run `pnpm test` to execute all tests
+- Use `pnpm test:watch` for development
+
+### Package Development
+
+- Each package in `packages/` should be self-contained
+- Follow the existing package structure and naming conventions
+- Update package README files when adding new functionality
+- Ensure all packages build successfully with `pnpm build`
+
+### Commit Messages
+
+Use clear, conventional commit messages:
+
+```bash
+feat: add new text normalization function
+fix: correct boundary checking logic
+docs: update package README
+test: add unit tests for diff parser
+refactor: simplify profile resolution
+```
+
+### Architecture Decisions
+
+- For significant architectural changes, create an **ADR** (Architecture Decision Record) 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
+
+## 🔄 Pull Request Process
+
+### Before Submitting
+
+1. **Fork** the repository and create a feature branch
+2. **Make your changes** following the guidelines above
+3. **Run quality checks:**
+   ```bash
+   pnpm check  # Runs lint + type-check + tests
+   ```
+4. **Update documentation** if needed (README files, inline comments)
+5. **Test your changes** thoroughly
+
+### Submitting the PR
+
+1. **Push** your changes to your fork
+2. **Create a Pull Request** with:
+   - Clear title describing the change
+   - Detailed description of what was changed and why
+   - Reference any related issues
+   - Screenshots or examples if applicable
+
+### Review Process
+
+- All PRs require review before merging
+- Address feedback promptly and professionally
+- Keep PRs focused and reasonably sized
+- Update your branch if the main branch has moved forward
+
+## 🐛 Reporting Issues
+
+When reporting bugs or requesting features:
+
+1. **Check existing issues** to avoid duplicates
+2. **Provide clear reproduction steps** for bugs
+3. **Include environment details** (Node.js version, OS, etc.)
+4. **Use appropriate labels** and templates
+
+## 📚 Additional Resources
+
+- [Architecture Decision Records](./docs/adr/) - Project architecture decisions
+- [Package Documentation](./packages/) - Individual package README files
+- [Development Scripts](./README.md#-available-scripts) - Available npm scripts
+
+---
+
+**See [Documentation Standard](./docs/DOCUMENTATION.md) for complete documentation guidelines.**

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) KB Labs
+
+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.