@kb-labs/devkit 1.0.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/CODEOWNERS

@@ -0,0 +1,2 @@
+# Default owner for everything — change if/when you add collaborators
+* @KirillBaranov

package/.github/actions/setup-node-pnpm/action.yml

@@ -0,0 +1,47 @@
+name: Setup Node & pnpm
+description: Install Node and pnpm with cache
+
+inputs:
+  node-version:
+    default: '20'
+  package-json-path:
+    default: 'package.json'
+  fallback-pnpm-version:
+    default: '9.15.0'
+
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-node@v4
+      with:
+        node-version: ${{ inputs.node-version }}
+        # cache: pnpm   ← УДАЛИТЬ
+
+    - name: Enable Corepack
+      shell: bash
+      run: |
+        corepack enable
+        echo "$HOME/.local/share/pnpm" >> "$GITHUB_PATH"
+        echo "$HOME/.local/share/node" >> "$GITHUB_PATH"
+
+    - name: Resolve PNPM version & activate via Corepack
+      shell: bash
+      run: |
+        set -euo pipefail
+        FILE="${{ inputs.package-json-path }}"
+        VER=$(node -e "try{const pm=require('${FILE}').packageManager||''; const v=(pm.split('@')[1]||'').split('+')[0]; process.stdout.write(v);}catch(e){process.stdout.write('');}")
+        [ -z "$VER" ] && VER="${{ inputs.fallback-pnpm-version }}"
+        echo "Using pnpm@$VER"
+        corepack prepare "pnpm@$VER" --activate
+        pnpm -v
+
+    - name: (opt) Cache pnpm store
+      uses: actions/cache@v4
+      with:
+        path: ~/.pnpm-store
+        key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
+        restore-keys: |
+          ${{ runner.os }}-pnpm-
+    - name: (opt) Configure pnpm store
+      shell: bash
+      run: pnpm config set store-dir ~/.pnpm-store

package/.github/workflow-templates/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/workflow-templates/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/workflow-templates/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/workflow-templates/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/.github/workflows/ci-reusable.yml

@@ -0,0 +1,131 @@
+name: reusable-ci
+
+on:
+  workflow_call:
+    inputs:
+      node-version:
+        description: Node.js version
+        required: false
+        default: '20'
+        type: string
+      run-coverage:
+        description: Run coverage step
+        required: false
+        default: true
+        type: boolean
+      enable-drift-check:
+        description: Run DevKit drift check (fails on drift)
+        required: false
+        default: true
+        type: boolean
+
+jobs:
+  drift:
+    if: ${{ inputs.enable-drift-check == true }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}-drift
+      cancel-in-progress: true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: KirillBaranov/kb-labs-devkit/.github/actions/setup-node-pnpm@main
+        with:
+          node-version: ${{ inputs['node-version'] }}
+      - name: Install deps
+        run: pnpm i --frozen-lockfile
+      - name: DevKit drift check
+        # Repos are expected to ship a script `devkit:check` that runs the sync tool in check mode
+        run: pnpm -s devkit:check
+
+  validate:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}-validate
+      cancel-in-progress: true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: KirillBaranov/kb-labs-devkit/.github/actions/setup-node-pnpm@main
+        with:
+          node-version: ${{ inputs['node-version'] }}
+      - name: Install deps
+        run: pnpm i --frozen-lockfile
+      - name: Lint
+        run: pnpm lint
+      - name: Type check
+        run: pnpm type-check || true
+
+  build:
+    runs-on: ubuntu-latest
+    needs: validate
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: KirillBaranov/kb-labs-devkit/.github/actions/setup-node-pnpm@main
+        with:
+          node-version: ${{ inputs['node-version'] }}
+      - name: Install deps
+        run: pnpm i --frozen-lockfile
+      - name: Build (workspace)
+        run: pnpm -r run build || true
+      - name: Upload build outputs
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-dist
+          path: |
+            packages/**/dist/
+            dist/
+          if-no-files-found: ignore
+
+  test:
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: KirillBaranov/kb-labs-devkit/.github/actions/setup-node-pnpm@main
+        with:
+          node-version: ${{ inputs['node-version'] }}
+      - name: Install deps
+        run: pnpm i --frozen-lockfile
+      - name: Download build outputs
+        uses: actions/download-artifact@v4
+        with:
+          name: build-dist
+          path: .
+      - name: Test (no watch)
+        run: pnpm test -- --run
+
+  coverage:
+    if: ${{ inputs['run-coverage'] == true }}
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: KirillBaranov/kb-labs-devkit/.github/actions/setup-node-pnpm@main
+        with:
+          node-version: ${{ inputs['node-version'] }}
+      - name: Install deps
+        run: pnpm i --frozen-lockfile
+      - name: Download build outputs
+        uses: actions/download-artifact@v4
+        with:
+          name: build-dist
+          path: .
+      - name: Coverage
+        run: pnpm test:coverage
+      - name: Upload coverage (if any)
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-html
+          path: |
+            coverage/
+            **/coverage/
+          if-no-files-found: ignore

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

@@ -0,0 +1,23 @@
+name: reusable-drift-check
+
+on:
+  workflow_call:
+    inputs:
+      node-version:
+        default: '20'
+        type: string
+
+jobs:
+  drift:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: KirillBaranov/kb-labs-devkit/.github/actions/setup-node-pnpm@main
+        with:
+          node-version: ${{ inputs.node-version }}
+      - run: pnpm i --frozen-lockfile
+      - name: DevKit drift check
+        run: |
+          pnpm -s devkit:check || \
+          node scripts/devkit-sync.mjs --check || \
+          ./node_modules/.bin/kb-devkit-sync --check

package/.github/workflows/fixtures.yml

@@ -0,0 +1,74 @@
+name: DevKit Fixtures
+
+on:
+  push:
+    branches: [ main ]
+    paths-ignore:
+      - '**/*.md'
+      - '**/.vscode/**'
+      - '**/.idea/**'
+  pull_request:
+    types: [opened, synchronize, reopened]
+  workflow_dispatch: {}
+  schedule:
+    - cron: '0 3 * * 1' # weekly canary (Mon 03:00 UTC)
+
+permissions:
+  contents: read
+
+concurrency:
+  group: devkit-fixtures-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  fixtures:
+    name: Run fixtures (all)
+    runs-on: ubuntu-latest
+    env:
+      CI: true
+
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+
+      - uses: KirillBaranov/kb-labs-devkit/.github/actions/setup-node-pnpm@main
+        with:
+          node-version: '20'
+
+      - name: Cache pnpm store
+        uses: actions/cache@v4
+        with:
+          path: ~/.pnpm-store
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - name: Install DevKit deps
+        run: pnpm i --frozen-lockfile
+
+      - name: Clean fixtures
+        run: pnpm fixtures:clean || true
+
+      - name: Bootstrap fixtures
+        run: pnpm fixtures:bootstrap
+
+      - name: Run fixtures (smart check)
+        shell: bash
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ] && [ -n "${{ github.base_ref }}" ]; then
+            echo "Running differential fixtures check since origin/${{ github.base_ref }}"
+            pnpm fixtures -- --action=check --since=origin/${{ github.base_ref }}
+          else
+            echo "Running full fixtures check"
+            pnpm fixtures:check
+          fi
+
+      - name: Upload artifacts (optional)
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: fixtures-artifacts
+          path: |
+            fixtures/**/coverage/**
+            fixtures/**/dist/**
+          if-no-files-found: ignore

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

@@ -0,0 +1,67 @@
+name: profiles-validate
+
+on:
+  workflow_call:
+    inputs:
+      node_version:
+        type: string
+        default: '20'
+      soft_fail:
+        type: boolean
+        default: true      # don't fail, while profiles are in development
+      working_directory:
+        type: string
+        default: '.'       # for monorepo — can specify the package path
+      log_level:
+        type: string
+        default: 'info'    # debug|info|warn|error
+      fixtures_dir:
+        type: string
+        default: ''        # optional, if there are presets/fixtures
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Detect .kb/profiles
+        id: detect
+        shell: bash
+        run: |
+          ROOT="${{ inputs.working_directory }}"
+          if [ -d "$ROOT/.kb/profiles" ]; then
+            echo "found=true" >> "$GITHUB_OUTPUT"
+            echo "[profiles] found at $ROOT/.kb/profiles"
+          else
+            echo "found=false" >> "$GITHUB_OUTPUT"
+            echo "[profiles] not found, skip"
+          fi
+
+      - name: Setup Node & pnpm
+        if: steps.detect.outputs.found == 'true'
+        uses: KirillBaranov/kb-labs-devkit/.github/actions/setup-node-pnpm@main
+        with:
+          node-version: ${{ inputs.node_version }}
+
+      - name: Install deps
+        if: steps.detect.outputs.found == 'true'
+        run: pnpm i --frozen-lockfile
+        working-directory: ${{ inputs.working_directory }}
+
+      - name: Validate profiles
+        if: steps.detect.outputs.found == 'true'
+        continue-on-error: ${{ inputs.soft_fail }}
+        env:
+          LOG_LEVEL: ${{ inputs.log_level }}
+          KB_PROFILES_FIXTURES: ${{ inputs.fixtures_dir }}
+        shell: bash
+        run: |
+          # if kb-CLI is available, use it, otherwise use the package schemas
+          if pnpm -s kb --help >/dev/null 2>&1; then
+            pnpm -s kb profiles validate
+          else
+            pnpm -F @kb-labs/profile-schemas -s run schemas:check
+          fi
+        working-directory: ${{ inputs.working_directory }}

package/.github/workflows/release-reusable.yml

@@ -0,0 +1,50 @@
+name: reusable-release
+
+on:
+  workflow_call:
+    inputs:
+      publish:
+        description: Publish to npm
+        required: false
+        default: false
+        type: boolean
+      node-version:
+        default: '20'
+        type: string
+    secrets:
+      NPM_TOKEN:
+        required: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      # Composite action: pnpm + Node + cache
+      - uses: KirillBaranov/kb-labs-devkit/.github/actions/setup-node-pnpm@main
+        with:
+          node-version: ${{ inputs['node-version'] }}
+
+      # Add registry for npm publish (separate step — так надёжнее)
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ inputs['node-version'] }}
+          cache: pnpm
+          registry-url: 'https://registry.npmjs.org'
+
+      - run: pnpm i --frozen-lockfile
+      - run: pnpm build || true
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+
+      - name: Publish to npm
+        if: ${{ inputs.publish == true }}
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: pnpm -r publish --access public --no-git-checks

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/AGENTS.md

@@ -0,0 +1,130 @@
+# KB Labs Agents
+
+The following agents are standardized across KB Labs projects. They live in this DevKit and can be synced into any repo.
+
+| Agent              | Folder                         | Purpose                                                        |
+|--------------------|--------------------------------|----------------------------------------------------------------|
+| DevKit Maintainer  | `agents/devkit-maintainer`     | Enforce unified tooling (tsconfig, eslint, prettier, vitest, tsup, CI). |
+| Test Generator     | `agents/test-generator`        | Generate and maintain pragmatic unit tests.                    |
+| Docs Drafter       | `agents/docs-drafter`          | Draft and update README/CONTRIBUTING/ADR docs.                 |
+| Release Manager    | `agents/release-manager`       | Prepare release plans, changelog, and GitHub releases.         |
+
+> These are **descriptions and prompts** to bootstrap Cursor Agents quickly.  
+> Use the `agents:sync` command in product repos to copy the latest agent definitions from this DevKit.
+
+## Agent Structure
+
+Each agent includes:
+
+- **`prompt.md`** — AI instructions and context for the agent
+- **`runbook.md`** — Step-by-step procedures and workflows
+- **`context.globs`** — File patterns for context (optional)
+- **`permissions.yml`** — Access permissions and restrictions (optional)
+
+## Usage
+
+### Syncing Agents
+
+To sync agents into your project:
+
+```bash
+# Copy all agent definitions from DevKit
+pnpm agents:sync
+
+# Or use the sync tool directly
+npx kb-devkit-sync agents
+```
+
+Agents are synced to `.kb/devkit/agents/` in your project.
+
+> **Note:** `.kb` is the common ecosystem folder. `devkit` is the product namespace. Each product decides what to store in their namespace. Product-specific agents can be added to `.kb/<product>/agents/` if needed.
+
+### Agent Configuration
+
+Agents are designed for Cursor AI but can be adapted for other IDE assistants:
+
+- **Cursor**: Place in `.cursor/agents/` directory
+- **GitHub Copilot Chat**: Adapt prompts for chat interface
+- **Other IDEs**: Modify prompts as needed for your environment
+
+### Customization
+
+You can customize agents by:
+
+1. **Extending prompts**: Add project-specific context to `prompt.md`
+2. **Modifying runbooks**: Update procedures in `runbook.md` for your workflow
+3. **Adjusting context**: Modify `context.globs` to include relevant files
+4. **Setting permissions**: Configure `permissions.yml` for security
+
+## Agent Details
+
+### DevKit Maintainer
+
+**Purpose**: Enforce unified tooling across KB Labs projects
+
+**Key Responsibilities**:
+- Ensure consistent tsconfig, eslint, prettier, vitest, tsup configurations
+- Validate CI/CD workflows and drift checks
+- Maintain DevKit synchronization
+- Enforce coding standards and best practices
+
+**Context**: Configuration files, CI workflows, package.json, DevKit sync files
+
+### Test Generator
+
+**Purpose**: Generate and maintain pragmatic unit tests
+
+**Key Responsibilities**:
+- Create comprehensive test suites for new features
+- Maintain existing tests and update when code changes
+- Ensure good test coverage and quality
+- Follow testing best practices and patterns
+
+**Context**: Source code files, existing tests, test configuration
+
+### Docs Drafter
+
+**Purpose**: Draft and update documentation
+
+**Key Responsibilities**:
+- Create and maintain README files
+- Update CONTRIBUTING guidelines
+- Draft Architecture Decision Records (ADRs)
+- Ensure documentation is clear and up-to-date
+
+**Context**: Project files, existing documentation, code structure
+
+### Release Manager
+
+**Purpose**: Prepare release plans, changelog, and GitHub releases
+
+**Key Responsibilities**:
+- Create release plans and versioning strategies
+- Generate changelogs from commit history
+- Prepare GitHub releases with proper tagging
+- Coordinate release processes across teams
+
+**Context**: Git history, package.json, release notes, version tags
+
+## Best Practices
+
+1. **Keep agents focused**: Each agent should have a clear, specific purpose
+2. **Update regularly**: Sync agents frequently to get latest improvements
+3. **Customize thoughtfully**: Adapt agents for your project while maintaining consistency
+4. **Test thoroughly**: Validate agent behavior before deploying to team
+5. **Document changes**: Keep track of customizations and their rationale
+
+## Troubleshooting
+
+### Common Issues
+
+- **Agent not responding**: Check that agent files are properly synced and accessible
+- **Incorrect context**: Verify `context.globs` patterns match your project structure
+- **Permission errors**: Review `permissions.yml` settings
+- **Outdated agents**: Run `pnpm agents:sync` to get latest versions
+
+### Getting Help
+
+- Check agent runbooks for detailed procedures
+- Review DevKit documentation for sync and configuration options
+- Open issues for agent-specific problems or suggestions

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.