@kb-labs/devkit 1.4.0 → 2.9.0

package/assets/claude/skills/kb-labs-troubleshoot/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: kb-labs-troubleshoot
+description: Use when the user reports a KB Labs problem — service stuck, build failing, command not found, port conflict, plugin not discovered, kb-dev reports failed, pnpm install errors, or asks "what is wrong with kb-labs".
+user-invocable: true
+---
+
+# KB Labs Troubleshooter
+
+Diagnose and fix common KB Labs platform issues. Work systematically from
+environment → services → plugins → build.
+
+## Step 0: Always start with doctor
+
+```bash
+kb-create doctor
+```
+
+This checks: node version, pnpm version, platform directory, installed manifest,
+git status of key files. Most problems surface here.
+
+## Step 1: "Command not found" or "Unknown command"
+
+Most common cause: **stale plugin registry cache after building a plugin**.
+
+```bash
+pnpm kb marketplace clear-cache
+```
+
+If that does not help, deep clear:
+
+```bash
+pnpm kb marketplace clear-cache --deep
+```
+
+Then retry the command. If it is still missing:
+
+```bash
+pnpm kb --help                    # is the group even present?
+pnpm kb <group> --help            # is the command in the group?
+pnpm kb plugins list              # is the plugin installed?
+```
+
+## Step 2: "Plugin not found" or wrong plugins in the available list
+
+Symptom: `Plugin not found: @kb-labs/qa` or the available list shows only
+test/workspace plugins.
+
+Cause: zombie host-agent daemon processes connected to Gateway are intercepting
+plugin execution with a stale local resolver.
+
+Fix:
+
+```bash
+pkill -9 -f "host-agent-app/dist/index.js"
+ps aux | grep host-agent | grep -v grep   # must be empty
+pnpm kb marketplace clear-cache --deep
+```
+
+Then retry the command.
+
+## Step 3: Service stuck in `failed` / `starting` / "port in use"
+
+```bash
+pnpm kb-dev status
+pnpm kb-dev logs <service>
+pnpm kb-dev doctor
+```
+
+Common fixes:
+
+```bash
+pnpm kb-dev start <service> --force        # kill port conflicts then start
+pnpm kb-dev restart <service>              # restart + cascade dependents
+pnpm kb-dev stop <service> --cascade       # stop service + dependents
+```
+
+Rules:
+- Never start services with raw `node` or `pnpm *:dev` — always use `kb-dev`.
+- If the service crashes repeatedly, run with `pnpm kb-dev start --watch` and
+  inspect the crash logs.
+
+## Step 4: Dirty submodule / "worktree has modifications"
+
+Cause: runtime files inside `.kb/` that are accidentally tracked or cross-repo
+link: paths that are stale.
+
+```bash
+git status
+pnpm kb devlink status
+pnpm kb devlink switch --mode=local --install
+```
+
+If the user is on a worktree, `pnpm done` style scripts intentionally skip
+certain QA stages — this is expected and not a bug.
+
+## Step 5: Build failures — "Cannot find module @kb-labs/..."
+
+Cause: wrong build order. Dependencies are not built before dependents.
+
+```bash
+npx kb-devkit-build-order --package=<your-package>
+npx kb-devkit-build-order --package=<your-package> --script | bash
+```
+
+Never run `pnpm -r build` for cross-repo build order — it does not understand
+dts dependency chains. Always use the devkit build-order tool.
+
+## Step 6: Type errors after a core change
+
+```bash
+npx kb-devkit-types-audit --package=<your-package>
+npx kb-devkit-types-order --package=<your-package>
+```
+
+Rebuild in types order.
+
+## Step 7: Cannot find `.kb/kb.config.json`
+
+This file is the platform's main configuration. **Do not try to recreate it.**
+
+- If the user accidentally deleted it → ask them to restore from backup or git.
+- If it was never created → run `kb-create` from the project root again.
+- Do not fabricate its contents.
+
+## Step 8: pnpm install errors with "workspace:" protocol
+
+Usually means the project's workspace yaml is missing cross-repo paths.
+
+```bash
+pnpm kb devlink switch --mode=local --install
+```
+
+## Step 9: Still stuck
+
+Collect diagnostics and suggest the user open an issue:
+
+```bash
+kb-create doctor --json > /tmp/kb-doctor.json
+pnpm kb-dev status --json > /tmp/kb-dev-status.json
+pnpm kb-dev logs <service> | tail -100 > /tmp/kb-service.log
+```
+
+## Important rules
+
+- **Never delete `.kb/kb.config.json`** under any circumstance.
+- **Never delete `.kb/mind/` or `.kb/cache/`** without asking — they may hold
+  expensive precomputed state.
+- **Never edit files inside `.kb/` by hand** — it is platform runtime state.
+- Prefer `kb-dev` commands over raw shell kills for service management.
+- Prefer `kb devlink` over manually editing package.json workspace entries.

package/assets/claude/skills/kb-labs-update/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: kb-labs-update
+description: Use when the user wants to update the installed KB Labs platform, upgrade to a new version, or asks "is there an update". Do not use for updating plugins (handled by the marketplace) or for pnpm-level dependency bumps.
+user-invocable: true
+---
+
+# Update the KB Labs Platform
+
+Guide the user through a safe platform update using `kb-create update`.
+
+## Step 1: Show current install
+
+Before updating, show what is currently installed so the user can confirm:
+
+```bash
+kb-create status
+```
+
+## Step 2: Run the update with a dry diff
+
+`kb-create update` already computes and prints the diff before applying
+anything. Run it:
+
+```bash
+kb-create update
+```
+
+Expected output:
+
+- a list of added / updated / removed packages
+- a confirmation prompt before applying
+
+Review the diff with the user. Watch for:
+
+- **Removed packages** — was this intentional? If not, abort.
+- **Major version bumps** — check release notes before accepting.
+- **Core packages** (`@kb-labs/core-*`) — these affect plugin compatibility.
+
+If the user is unsure, they can abort at the prompt — nothing has been written
+at that point.
+
+## Step 3: Apply the update
+
+Confirm at the prompt. After `kb-create` finishes, it will also refresh Claude
+Code assets under `.claude/skills/kb-labs-*` and the managed CLAUDE.md section.
+
+## Step 4: Verify the update
+
+```bash
+kb-create doctor
+kb-create status
+pnpm kb --help
+```
+
+If services are configured:
+
+```bash
+pnpm kb-dev restart
+pnpm kb-dev status
+```
+
+## Step 5: Clear stale caches
+
+After an update, plugin manifests may have changed:
+
+```bash
+pnpm kb marketplace clear-cache
+```
+
+## If the update fails partway
+
+Do not try to fix things by hand. Run:
+
+```bash
+kb-create doctor --json
+```
+
+and switch to the `kb-labs-troubleshoot` skill.
+
+## Important rules
+
+- Never bypass `kb-create update` by running `pnpm update @kb-labs/*` manually —
+  the launcher tracks state and resolves cross-package versions; manual bumps
+  will desynchronise the install.
+- Never delete `.kb/kb.config.json` to "start fresh" — it is the main platform
+  config and cannot be trivially recreated.
+- If the user wants to downgrade, the cleanest path is `kb-create uninstall`
+  followed by `kb-create` at the desired version. Warn them that project state
+  under `.kb/` is preserved by default but plugin data may be incompatible.

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@kb-labs/devkit",
-  "version": "1.4.0",
+  "version": "2.9.0",
   "type": "module",
   "description": "Shared developer toolkit for KB Labs projects: TS/ESLint/Prettier/Vitest/Tsup presets and reusable GitHub Actions.",
   "files": [
     "agents",
-    ".cursorrules",
+    "assets",
     "tsconfig",
     "eslint",
     "prettier",
@@ -14,7 +14,6 @@
     "tsup",
     "templates",
     ".github",
-    ".vscode",
     "bin",
     "sync",
     "AGENTS.md",
@@ -61,6 +60,7 @@
     "./tsconfig/node.json": "./tsconfig/node.json",
     "./tsconfig/react-lib.json": "./tsconfig/react-lib.json",
     "./tsconfig/react-app.json": "./tsconfig/react-app.json",
+    "./tsconfig/spa.json": "./tsconfig/spa.json",
     "./tsconfig/test.json": "./tsconfig/test.json",
     "./eslint/": "./eslint/",
     "./eslint/node.js": "./eslint/node.js",
@@ -91,8 +91,8 @@
     "./tsup/sdk": "./tsup/sdk.js",
     "./tsup/dual": "./tsup/dual.js",
     "./agents/": "./agents/",
-    "./cursorrules": "./.cursorrules",
-    "./.vscode/settings.json": "./.vscode/settings.json",
+    "./assets/": "./assets/",
+    "./assets/claude/manifest.json": "./assets/claude/manifest.json",
     "./AGENTS.md": "./AGENTS.md",
     "./bin/devkit-sync.mjs": "./bin/devkit-sync.mjs",
     "./bin/devkit-paths.mjs": "./bin/devkit-paths.mjs",
@@ -103,26 +103,6 @@
     "./tsup/external-sync": "./tsup/external-sync.mjs",
     "./sync": "./sync/index.mjs"
   },
-  "scripts": {
-    "clean": "rimraf dist",
-    "build": "echo \"@kb-labs/devkit: nothing to build\"",
-    "lint": "echo \"@kb-labs/devkit: lint skipped (plain JS/MJS, not TS project)\" && exit 0",
-    "lint:fix": "eslint . --fix --ignore-pattern 'dist/**'",
-    "test": "vitest run --passWithNoTests",
-    "test:watch": "vitest --passWithNoTests",
-    "paths": "node ./bin/devkit-paths.mjs",
-    "fixtures": "node scripts/fixtures.js –help",
-    "fixtures:check": "node scripts/fixtures.js –action=check",
-    "fixtures:lint": "node scripts/fixtures.js –action=lint",
-    "fixtures:test": "node scripts/fixtures.js –action=test",
-    "fixtures:build": "node scripts/fixtures.js –action=build",
-    "fixtures:bootstrap": "node scripts/fixtures.js –action=bootstrap",
-    "fixtures:clean": "node scripts/fixtures.js –action=clean",
-    "fixtures:ci": "node scripts/fixtures.js –action=check –since=${GITHUB_BASE_REF:-origin/main} –concurrency=3 || node scripts/fixtures.js –action=check",
-    "postinstall": "kb-devkit-tsup-external --generate || true",
-    "dev": "tsup --config tsup.config.ts --watch",
-    "type-check": "echo \"@kb-labs/devkit: type-check skipped (plain JS/MJS, not TS project)\" && exit 0"
-  },
   "peerDependencies": {
     "@playwright/test": "*",
     "eslint": "^9.35.0",
@@ -164,8 +144,8 @@
     "yaml": "^2.8.0"
   },
   "devDependencies": {
-    "@kb-labs/devkit": "link:./",
     "@types/node": "^24.3.3",
+    "@vitest/coverage-istanbul": "3.2.4",
     "@vitest/coverage-v8": "^3.2.4",
     "eslint": "^9.35.0",
     "eslint-plugin-filenames-simple": "^0.9.0",
@@ -177,9 +157,9 @@
     "tsup": "^8.5.0",
     "typescript": "^5.9.2",
     "typescript-eslint": "^8.44.0",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "@kb-labs/devkit": "2.9.0"
   },
-  "packageManager": "pnpm@9.11.0+sha512.0a203ffaed5a3f63242cd064c8fb5892366c103e328079318f78062f24ea8c9d50bc6a47aa3567cabefd824d170e78fa2745ed1f16b132e16436146b7688f19b",
   "engines": {
     "node": ">=20.0.0",
     "pnpm": ">=9.11.0"
@@ -187,5 +167,25 @@
   "license": "MIT",
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "echo \"@kb-labs/devkit: nothing to build\"",
+    "lint": "echo \"@kb-labs/devkit: lint skipped (plain JS/MJS, not TS project)\" && exit 0",
+    "lint:fix": "eslint . --fix --ignore-pattern 'dist/**'",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest --passWithNoTests",
+    "paths": "node ./bin/devkit-paths.mjs",
+    "fixtures": "node scripts/fixtures.js –help",
+    "fixtures:check": "node scripts/fixtures.js –action=check",
+    "fixtures:lint": "node scripts/fixtures.js –action=lint",
+    "fixtures:test": "node scripts/fixtures.js –action=test",
+    "fixtures:build": "node scripts/fixtures.js –action=build",
+    "fixtures:bootstrap": "node scripts/fixtures.js –action=bootstrap",
+    "fixtures:clean": "node scripts/fixtures.js –action=clean",
+    "fixtures:ci": "node scripts/fixtures.js –action=check –since=${GITHUB_BASE_REF:-origin/main} –concurrency=3 || node scripts/fixtures.js –action=check",
+    "postinstall": "kb-devkit-tsup-external --generate || true",
+    "dev": "tsup --config tsup.config.ts --watch",
+    "type-check": "echo \"@kb-labs/devkit: type-check skipped (plain JS/MJS, not TS project)\" && exit 0"
   }
-}
+}

package/tsconfig/spa.json

@@ -0,0 +1,7 @@
+{
+  "extends": "./react-app.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "declaration": false
+  }
+}

package/vitest/node.js

@@ -17,14 +17,20 @@ export default defineConfig({
       provider: 'v8',
       all: true,
       reportsDirectory: './coverage',
-      reporter: ['text', 'html', 'lcov'],
+      reporter: ['text', 'json', 'lcov'],
       exclude: [
         '**/node_modules/**',
         '**/dist/**',
         '**/__tests__/**',
         '**/*.d.ts',
         '**/types.ts',
-        '**/types/**'
+        '**/types/**',
+        '**/contracts.ts',
+        '**/contracts/**',
+        '**/constants.ts',
+        '**/constants/**',
+        '**/*.config.ts',
+        '**/*.config.js'
       ],
       thresholds: {
         statements: 90,

package/vitest/react.js

@@ -18,14 +18,20 @@ export default defineConfig({
       provider: 'v8',
       all: true,
       reportsDirectory: './coverage',
-      reporter: ['text', 'html', 'lcov'],
+      reporter: ['text', 'json', 'lcov'],
       exclude: [
         '**/node_modules/**',
         '**/dist/**',
         '**/__tests__/**',
         '**/*.d.ts',
         '**/types.ts',
-        '**/types/**'
+        '**/types/**',
+        '**/contracts.ts',
+        '**/contracts/**',
+        '**/constants.ts',
+        '**/constants/**',
+        '**/*.config.ts',
+        '**/*.config.js'
       ],
       thresholds: {
         statements: 90,

package/.cursorrules

@@ -1,32 +0,0 @@
-# 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

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

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

@@ -1,47 +0,0 @@
-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

@@ -1,13 +0,0 @@
-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/deploy.yml

@@ -1,28 +0,0 @@
-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/workflow-templates/docker-build.yml

@@ -1,25 +0,0 @@
-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/workflow-templates/drift-check.yml

@@ -1,10 +0,0 @@
-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

@@ -1,16 +0,0 @@
-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

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