@kb-labs/devkit 1.0.0

package/templates/package-json/README.md

@@ -0,0 +1,290 @@
+# Package.json Templates
+
+Standard package.json templates for KB Labs monorepo packages.
+
+## Philosophy
+
+**Minimum Required Standard:**
+- All packages MUST have the sections and scripts defined in these templates
+- Packages CAN add MORE sections and scripts as needed
+- Packages CANNOT have LESS than the standard (enforced by `kb-devkit-check-structure`)
+
+## Templates
+
+### Library Package (Standard)
+**File:** `package.json.template`
+
+**Use for:** Most packages (90%)
+- Core libraries
+- Contracts packages
+- Utilities
+- API clients
+
+**Required sections:**
+- `name`, `version`, `type`, `private`, `description`
+- `main`, `types`, `exports`
+- `files`, `sideEffects`
+- `scripts` (8 required scripts)
+- `dependencies`, `devDependencies`
+- `engines`
+
+**Required scripts:**
+```json
+{
+  "clean": "rimraf dist",
+  "build": "tsup --config tsup.config.ts",
+  "dev": "tsup --config tsup.config.ts --watch",
+  "lint": "eslint src --ext .ts",
+  "lint:fix": "eslint src --ext .ts --fix",
+  "type-check": "tsc --noEmit",
+  "test": "vitest run",
+  "test:watch": "vitest"
+}
+```
+
+### Binary Package
+**File:** `package.json.bin.template`
+
+**Use for:** CLI binaries
+- `cli-bin`
+- Daemon executables
+- Standalone tools
+
+**Differences from library:**
+- Has `bin` field instead of `main`/`types`
+- No `exports` (binaries don't export modules)
+
+## Required DevDependencies
+
+**All packages MUST have:**
+```json
+{
+  "@kb-labs/devkit": "workspace:*",
+  "@types/node": "^24.3.3",
+  "rimraf": "^6.0.1",
+  "tsup": "^8.5.0",
+  "typescript": "^5.6.3",
+  "vitest": "^3.2.4"
+}
+```
+
+**Why these are required:**
+- `@kb-labs/devkit` - Build system presets (tsup, eslint, tsconfig)
+- `@types/node` - TypeScript types for Node.js
+- `rimraf` - Cross-platform file deletion (clean script)
+- `tsup` - Build tool (used in all packages)
+- `typescript` - TypeScript compiler (type-check script)
+- `vitest` - Test runner (test scripts)
+
+## Optional Additions
+
+**Packages CAN add:**
+- Additional scripts (e.g., `test:benchmarks`, `test:all`)
+- Additional dependencies
+- Additional `exports` entries (subpath exports)
+- Custom fields (e.g., `repository`, `keywords`)
+
+**Examples:**
+```json
+{
+  "scripts": {
+    // ✅ Required scripts (must have all 8)
+    "clean": "rimraf dist",
+    "build": "tsup --config tsup.config.ts",
+    "dev": "tsup --config tsup.config.ts --watch",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+
+    // ✅ Additional scripts (OK to add)
+    "test:benchmarks": "vitest run tests/benchmarks",
+    "test:all": "vitest run && vitest run tests/benchmarks",
+    "pretype-check": "pnpm --filter @kb-labs/package build"
+  },
+  "exports": {
+    // ✅ Required default export
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    // ✅ Additional exports (OK to add)
+    "./analyzer": {
+      "import": "./dist/analyzer/index.js",
+      "types": "./dist/analyzer/index.d.ts"
+    }
+  }
+}
+```
+
+## Validation
+
+**Check package.json structure:**
+```bash
+npx kb-devkit-check-structure
+```
+
+**What it checks:**
+- ✅ All required sections present
+- ✅ All required scripts present
+- ✅ All required devDependencies present
+- ✅ Correct `type: "module"`
+- ✅ Correct `engines` versions
+- ⚠️ Warns about missing optional sections (repository, keywords)
+
+**Auto-fix missing scripts:**
+```bash
+npx kb-devkit-check-structure --fix
+```
+
+## Common Issues
+
+### Missing Scripts
+
+**Problem:**
+```bash
+pnpm -r run test
+# ❌ Error: "test" script not found in @kb-labs/some-package
+```
+
+**Solution:**
+```bash
+# Check which packages are missing scripts
+npx kb-devkit-check-structure
+
+# Auto-add missing scripts
+npx kb-devkit-check-structure --fix
+```
+
+### Wrong Script Names
+
+**Problem:**
+```json
+{
+  "scripts": {
+    "test:unit": "vitest run"  // ❌ Wrong, should be "test"
+  }
+}
+```
+
+**Solution:**
+```json
+{
+  "scripts": {
+    "test": "vitest run",           // ✅ Required
+    "test:unit": "vitest run"       // ✅ Additional is OK
+  }
+}
+```
+
+### Missing DevDependencies
+
+**Problem:**
+```bash
+pnpm run build
+# ❌ Error: Cannot find module 'tsup'
+```
+
+**Solution:**
+```bash
+# Check missing devDependencies
+npx kb-devkit-check-structure --verbose
+
+# Install missing deps
+pnpm install
+```
+
+## Migration Guide
+
+**For existing packages:**
+
+1. **Check current status:**
+   ```bash
+   npx kb-devkit-check-structure --package=@kb-labs/your-package
+   ```
+
+2. **Add missing scripts:**
+   ```bash
+   npx kb-devkit-check-structure --package=@kb-labs/your-package --fix
+   ```
+
+3. **Verify:**
+   ```bash
+   cd packages/your-package
+   pnpm run build
+   pnpm run test
+   pnpm run lint
+   ```
+
+**For new packages:**
+
+1. **Copy template:**
+   ```bash
+   cp kb-labs-devkit/templates/package-json/package.json.template package.json
+   ```
+
+2. **Update metadata:**
+   - Change `name` to your package name
+   - Update `description`
+   - Add dependencies
+
+3. **Verify:**
+   ```bash
+   npx kb-devkit-check-structure --package=@kb-labs/your-package
+   ```
+
+## Design Decisions
+
+### Why "More is OK, Less is Not"?
+
+**Consistency vs Flexibility:**
+- **Minimum standard** ensures all packages work with monorepo scripts (`pnpm -r run build`)
+- **Additional scripts** allow package-specific needs (benchmarks, integration tests)
+- **Enforced baseline** prevents "missing script" errors in CI/CD
+
+### Why These Exact Scripts?
+
+**Based on actual usage:**
+- `clean` - Required before rebuild (prevents stale artifacts)
+- `build` - Used by CI, pre-commit hooks, dependencies
+- `dev` - Developer workflow (watch mode)
+- `lint` - Code quality checks
+- `lint:fix` - Auto-fix linting issues
+- `type-check` - TypeScript validation (separate from build)
+- `test` - CI test runs
+- `test:watch` - Developer workflow (TDD)
+
+### Why Vitest (not Jest)?
+
+**Modern, fast, ESM-native:**
+- ✅ Native ESM support (no config needed)
+- ✅ 10x faster than Jest for small tests
+- ✅ Compatible with Vite ecosystem
+- ✅ Built-in TypeScript support
+- ✅ Watch mode with UI
+
+**Migration from Jest:**
+```bash
+# Replace jest with vitest
+pnpm remove jest @types/jest
+pnpm add -D vitest
+
+# Update scripts
+# "test": "jest" → "test": "vitest run"
+# "test:watch": "jest --watch" → "test:watch": "vitest"
+```
+
+## Future Improvements
+
+**Planned features:**
+- Auto-migration tool (`kb-devkit-migrate-package-json`)
+- Version alignment checker (ensure all packages use same vitest/tsup versions)
+- Script validation (ensure scripts actually work)
+- Dependency audit (find unused deps)
+
+## See Also
+
+- [Config Templates](../configs/README.md) - tsup, eslint, tsconfig templates
+- [DevKit README](../../README.md) - Complete DevKit documentation
+- [Check Structure Tool](../../bin/devkit-check-structure.mjs) - Validation script

package/templates/package-json/package.json.bin.template

@@ -0,0 +1,40 @@
+{
+  "$comment": "Binary package template for @kb-labs CLI binaries",
+  "name": "@kb-labs/package-bin",
+  "version": "0.1.0",
+  "type": "module",
+  "private": true,
+  "description": "CLI binary package",
+  "bin": {
+    "kb": "./dist/bin.cjs"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsup --config tsup.config.ts",
+    "dev": "tsup --config tsup.config.ts --watch",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@kb-labs/devkit": "workspace:*",
+    "@types/node": "^24.3.3",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  }
+}

package/templates/package-json/package.json.template

@@ -0,0 +1,45 @@
+{
+  "$comment": "Standard package.json template for @kb-labs packages",
+  "name": "@kb-labs/package-name",
+  "version": "0.1.0",
+  "type": "module",
+  "private": true,
+  "description": "Package description",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsup --config tsup.config.ts",
+    "dev": "tsup --config tsup.config.ts --watch",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@kb-labs/devkit": "workspace:*",
+    "@types/node": "^24.3.3",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  }
+}

package/tsconfig/base.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": [
+      "ES2022"
+    ],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,
+    "sourceMap": true
+  }
+}

package/tsconfig/cli.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": [
+    "src",
+    "bin"
+  ]
+}

package/tsconfig/dist/__tests__/cache.spec.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @module @kb-labs/core/config/__tests__/cache.spec.ts
+ * Tests for filesystem cache functionality
+ */
+export {};
+//# sourceMappingURL=cache.spec.d.ts.map

package/tsconfig/dist/__tests__/cache.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.spec.d.ts","sourceRoot":"","sources":["../../../../kb-labs-core/packages/config/src/__tests__/cache.spec.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/tsconfig/dist/__tests__/cache.spec.js

@@ -0,0 +1,85 @@
+/**
+ * @module @kb-labs/core/config/__tests__/cache.spec.ts
+ * Tests for filesystem cache functionality
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fsp } from 'node:fs';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { fsCache, clearCaches } from '../cache/fs-cache';
+import { readConfigFile } from '../api/read-config';
+describe('Filesystem Cache', () => {
+    let testDir;
+    beforeEach(async () => {
+        testDir = path.join(tmpdir(), `kb-labs-cache-test-${Date.now()}`);
+        await fsp.mkdir(testDir, { recursive: true });
+        clearCaches();
+    });
+    afterEach(async () => {
+        await fsp.rm(testDir, { recursive: true, force: true });
+        clearCaches();
+    });
+    describe('Cache Operations', () => {
+        it('should cache file reads', async () => {
+            const configPath = path.join(testDir, 'test-config.json');
+            const configData = { test: 'value' };
+            await fsp.writeFile(configPath, JSON.stringify(configData, null, 2));
+            // First read - should not be cached
+            const result1 = await readConfigFile(configPath);
+            expect(result1.data).toEqual(configData);
+            // Second read - should be cached
+            const result2 = await readConfigFile(configPath);
+            expect(result2.data).toEqual(configData);
+        });
+        it('should invalidate cache on file change', async () => {
+            const configPath = path.join(testDir, 'test-config.json');
+            const configData1 = { test: 'value1' };
+            const configData2 = { test: 'value2' };
+            await fsp.writeFile(configPath, JSON.stringify(configData1, null, 2));
+            // First read
+            const result1 = await readConfigFile(configPath);
+            expect(result1.data).toEqual(configData1);
+            // Small delay to ensure mtime changes
+            await new Promise(resolve => setTimeout(resolve, 10));
+            // Modify file
+            await fsp.writeFile(configPath, JSON.stringify(configData2, null, 2));
+            // Second read - should get new data
+            const result2 = await readConfigFile(configPath);
+            expect(result2.data).toEqual(configData2);
+        });
+        it('should clear caches', async () => {
+            const configPath = path.join(testDir, 'test-config.json');
+            const configData = { test: 'value' };
+            await fsp.writeFile(configPath, JSON.stringify(configData, null, 2));
+            // Read to populate cache
+            await readConfigFile(configPath);
+            // Clear cache
+            clearCaches();
+            // Verify cache is cleared by checking stats
+            const stats = fsCache.getStats();
+            expect(stats.size).toBe(0);
+        });
+        it('should handle YAML files', async () => {
+            const configPath = path.join(testDir, 'test-config.yaml');
+            const configData = { test: 'value', nested: { key: 'value' } };
+            await fsp.writeFile(configPath, `test: value\nnested:\n  key: value`);
+            const result = await readConfigFile(configPath);
+            expect(result.format).toBe('yaml');
+            expect(result.data).toEqual(configData);
+        });
+    });
+    describe('Cache Statistics', () => {
+        it('should track cache size', async () => {
+            const configPath1 = path.join(testDir, 'config1.json');
+            const configPath2 = path.join(testDir, 'config2.json');
+            await fsp.writeFile(configPath1, JSON.stringify({ test1: 'value1' }));
+            await fsp.writeFile(configPath2, JSON.stringify({ test2: 'value2' }));
+            // Read both files
+            await readConfigFile(configPath1);
+            await readConfigFile(configPath2);
+            const stats = fsCache.getStats();
+            expect(stats.size).toBeGreaterThan(0);
+        });
+    });
+});
+//# sourceMappingURL=cache.spec.js.map

package/tsconfig/dist/__tests__/cache.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.spec.js","sourceRoot":"","sources":["../../../../kb-labs-core/packages/config/src/__tests__/cache.spec.ts"],"names":[],"mappings":"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"}

package/tsconfig/dist/__tests__/fs-atomic.spec.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @module @kb-labs/core/config/__tests__/fs-atomic.spec.ts
+ * Tests for atomic file operations and workspace validation
+ */
+export {};
+//# sourceMappingURL=fs-atomic.spec.d.ts.map

package/tsconfig/dist/__tests__/fs-atomic.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-atomic.spec.d.ts","sourceRoot":"","sources":["../../../../kb-labs-core/packages/config/src/__tests__/fs-atomic.spec.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/tsconfig/dist/__tests__/fs-atomic.spec.js

@@ -0,0 +1,153 @@
+/**
+ * @module @kb-labs/core/config/__tests__/fs-atomic.spec.ts
+ * Tests for atomic file operations and workspace validation
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { promises as fsp } from 'node:fs';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { writeFileAtomic, ensureWithinWorkspace } from '../utils/fs-atomic';
+import { KbError } from '../errors/kb-error';
+describe('fs-atomic', () => {
+    let testDir;
+    beforeEach(async () => {
+        testDir = path.join(tmpdir(), `kb-labs-fs-atomic-test-${Date.now()}`);
+        await fsp.mkdir(testDir, { recursive: true });
+    });
+    afterEach(async () => {
+        await fsp.rm(testDir, { recursive: true, force: true });
+    });
+    describe('writeFileAtomic', () => {
+        it('should write file atomically', async () => {
+            const filePath = path.join(testDir, 'test.txt');
+            const content = 'Hello, World!';
+            await writeFileAtomic(filePath, content);
+            const result = await fsp.readFile(filePath, 'utf-8');
+            expect(result).toBe(content);
+        });
+        it('should create parent directories', async () => {
+            const filePath = path.join(testDir, 'nested', 'deep', 'test.txt');
+            const content = 'Nested content';
+            await writeFileAtomic(filePath, content);
+            const result = await fsp.readFile(filePath, 'utf-8');
+            expect(result).toBe(content);
+        });
+        it('should handle Uint8Array data', async () => {
+            const filePath = path.join(testDir, 'binary.txt');
+            const content = new Uint8Array([72, 101, 108, 108, 111]); // "Hello"
+            await writeFileAtomic(filePath, content);
+            const result = await fsp.readFile(filePath);
+            expect(Array.from(result)).toEqual(Array.from(content));
+        });
+        it('should clean up temp file on error', async () => {
+            const filePath = path.join(testDir, 'test.txt');
+            // Mock fs.writeFile to throw error
+            const originalWriteFile = fsp.writeFile;
+            vi.spyOn(fsp, 'writeFile').mockRejectedValueOnce(new Error('Write failed'));
+            await expect(writeFileAtomic(filePath, 'content')).rejects.toThrow('Write failed');
+            // Check that temp file was cleaned up
+            const files = await fsp.readdir(testDir);
+            const tempFiles = files.filter(f => f.startsWith('test.txt.tmp-'));
+            expect(tempFiles).toHaveLength(0);
+            // Restore original function
+            vi.restoreAllMocks();
+        });
+        it('should handle cleanup errors gracefully', async () => {
+            const filePath = path.join(testDir, 'test.txt');
+            // Mock fs.writeFile to throw error
+            const originalWriteFile = fsp.writeFile;
+            const originalUnlink = fsp.unlink;
+            vi.spyOn(fsp, 'writeFile').mockRejectedValueOnce(new Error('Write failed'));
+            vi.spyOn(fsp, 'unlink').mockRejectedValueOnce(new Error('Cleanup failed'));
+            // Should not throw cleanup error
+            await expect(writeFileAtomic(filePath, 'content')).rejects.toThrow('Write failed');
+            // Restore original functions
+            vi.restoreAllMocks();
+        });
+        it('should overwrite existing file', async () => {
+            const filePath = path.join(testDir, 'existing.txt');
+            const originalContent = 'Original content';
+            const newContent = 'New content';
+            // Create original file
+            await fsp.writeFile(filePath, originalContent);
+            // Overwrite atomically
+            await writeFileAtomic(filePath, newContent);
+            const result = await fsp.readFile(filePath, 'utf-8');
+            expect(result).toBe(newContent);
+        });
+        it('should generate unique temp file names', async () => {
+            const filePath = path.join(testDir, 'test.txt');
+            const content = 'content';
+            // Mock Date.now and Math.random for predictable temp names
+            const mockDateNow = vi.spyOn(Date, 'now').mockReturnValue(1234567890);
+            const mockMathRandom = vi.spyOn(Math, 'random').mockReturnValue(0.5);
+            await writeFileAtomic(filePath, content);
+            // Check that temp file name was generated correctly
+            const files = await fsp.readdir(testDir);
+            expect(files).toContain('test.txt');
+            mockDateNow.mockRestore();
+            mockMathRandom.mockRestore();
+        });
+    });
+    describe('ensureWithinWorkspace', () => {
+        it('should allow paths within workspace', () => {
+            const workspaceRoot = '/workspace';
+            const targetPath = '/workspace/subdir/file.txt';
+            expect(() => ensureWithinWorkspace(targetPath, workspaceRoot)).not.toThrow();
+        });
+        it('should allow relative paths within workspace', () => {
+            const workspaceRoot = '/workspace';
+            const targetPath = path.join(workspaceRoot, 'subdir', 'file.txt');
+            expect(() => ensureWithinWorkspace(targetPath, workspaceRoot)).not.toThrow();
+        });
+        it('should throw error for paths outside workspace', () => {
+            const workspaceRoot = '/workspace';
+            const targetPath = '/outside/file.txt';
+            expect(() => ensureWithinWorkspace(targetPath, workspaceRoot)).toThrow(KbError);
+        });
+        it('should throw error for paths that escape via ..', () => {
+            const workspaceRoot = '/workspace';
+            const targetPath = '/workspace/../outside/file.txt';
+            expect(() => ensureWithinWorkspace(targetPath, workspaceRoot)).toThrow(KbError);
+        });
+        it('should handle edge case with trailing slashes', () => {
+            const workspaceRoot = '/workspace/';
+            const targetPath = '/workspace/file.txt';
+            expect(() => ensureWithinWorkspace(targetPath, workspaceRoot)).not.toThrow();
+        });
+        it('should handle same directory as workspace', () => {
+            const workspaceRoot = '/workspace';
+            const targetPath = '/workspace';
+            expect(() => ensureWithinWorkspace(targetPath, workspaceRoot)).not.toThrow();
+        });
+        it('should throw error with correct error details', () => {
+            const workspaceRoot = '/workspace';
+            const targetPath = '/outside/file.txt';
+            expect(() => ensureWithinWorkspace(targetPath, workspaceRoot)).toThrow(expect.objectContaining({
+                code: 'ERR_PATH_OUTSIDE_WORKSPACE',
+                message: 'Refusing to write outside workspace: /outside/file.txt',
+                hint: 'Check cwd or use a relative path within the workspace',
+                meta: {
+                    targetPath: '/outside/file.txt',
+                    workspaceRoot: '/workspace',
+                },
+            }));
+        });
+        it('should handle empty workspace root', () => {
+            const workspaceRoot = '';
+            const targetPath = '/some/path';
+            expect(() => ensureWithinWorkspace(targetPath, workspaceRoot)).toThrow(KbError);
+        });
+        it('should handle empty target path', () => {
+            const workspaceRoot = '/workspace';
+            const targetPath = '';
+            expect(() => ensureWithinWorkspace(targetPath, workspaceRoot)).toThrow(KbError);
+        });
+        it('should resolve paths correctly', () => {
+            const workspaceRoot = '/workspace';
+            const targetPath = path.resolve(workspaceRoot, 'subdir', '..', 'subdir', 'file.txt');
+            expect(() => ensureWithinWorkspace(targetPath, workspaceRoot)).not.toThrow();
+        });
+    });
+});
+//# sourceMappingURL=fs-atomic.spec.js.map