@kb-labs/devkit 1.0.0

package/templates/configs/README.md

@@ -0,0 +1,306 @@
+# Standard Configuration Templates
+
+This directory contains canonical configuration templates for all `@kb-labs` packages.
+
+## 📋 Available Templates
+
+### Core Configs (All Packages)
+
+| File | Purpose | Required | Customizable |
+|------|---------|----------|--------------|
+| **eslint.config.js** | Linting rules | ✅ Yes | ⚠️ Minimal |
+| **tsconfig.json** | TypeScript IDE config | ✅ Yes | ❌ No |
+| **tsconfig.build.json** | TypeScript build config | ✅ Yes | ❌ No |
+
+### Tsup Configs (Choose ONE based on package type)
+
+| Template | Package Type | Use Cases |
+|----------|--------------|-----------|
+| **tsup.config.ts** | 📦 **Library** (default) | Most packages, importable libraries |
+| **tsup.config.bin.ts** | 🔧 **Binary** | Standalone executables, CLI bins |
+| **tsup.config.cli.ts** | ⌨️ **CLI** | CLI packages with commands |
+| **tsup.config.dual.ts** | 📦🔧 **Library + Binary** | Packages with both API and bin |
+
+### Package.json Examples
+
+| Template | Purpose |
+|----------|---------|
+| **package.json.lib** | Library package example |
+| **package.json.bin** | Binary package example |
+
+## 🎯 Philosophy
+
+**Convention over Configuration**
+
+All `@kb-labs` packages MUST use these exact templates with minimal customization. This ensures:
+
+- ✅ Consistent build output across all packages
+- ✅ Predictable dependency resolution
+- ✅ Unified linting standards
+- ✅ Easy maintenance and upgrades
+
+## 📦 Usage
+
+### For New Packages
+
+#### Step 1: Choose Package Type
+
+**Library Package** (most common):
+```bash
+cp kb-labs-devkit/templates/configs/tsup.config.ts your-package/
+cp kb-labs-devkit/templates/configs/eslint.config.js your-package/
+cp kb-labs-devkit/templates/configs/tsconfig*.json your-package/
+cp kb-labs-devkit/templates/configs/package.json.lib your-package/package.json
+```
+
+**Binary Package** (standalone executables):
+```bash
+cp kb-labs-devkit/templates/configs/tsup.config.bin.ts your-package/tsup.config.ts
+cp kb-labs-devkit/templates/configs/eslint.config.js your-package/
+cp kb-labs-devkit/templates/configs/tsconfig*.json your-package/
+cp kb-labs-devkit/templates/configs/package.json.bin your-package/package.json
+```
+
+**CLI Package** (command handlers):
+```bash
+cp kb-labs-devkit/templates/configs/tsup.config.cli.ts your-package/tsup.config.ts
+cp kb-labs-devkit/templates/configs/eslint.config.js your-package/
+cp kb-labs-devkit/templates/configs/tsconfig*.json your-package/
+cp kb-labs-devkit/templates/configs/package.json.lib your-package/package.json
+```
+
+**Dual Package** (library + binary):
+```bash
+cp kb-labs-devkit/templates/configs/tsup.config.dual.ts your-package/tsup.config.ts
+cp kb-labs-devkit/templates/configs/eslint.config.js your-package/
+cp kb-labs-devkit/templates/configs/tsconfig*.json your-package/
+cp kb-labs-devkit/templates/configs/package.json.lib your-package/package.json
+# Then add "bin" field to package.json
+```
+
+#### Step 2: Customize Package Name
+```bash
+# Edit package.json and update name, description
+```
+
+### For Existing Packages
+
+```bash
+# Check for drift
+npx kb-devkit-check-configs
+
+# Auto-fix drift
+npx kb-devkit-check-configs --fix
+```
+
+## 🔧 Customization Rules
+
+### tsup.config.ts
+
+**Allowed customizations:**
+
+```typescript
+export default defineConfig({
+  ...nodePreset,
+  tsconfig: 'tsconfig.build.json', // ✅ Always required
+
+  // ✅ OK: Multiple entry points
+  entry: ['src/index.ts', 'src/cli.ts'],
+
+  // ✅ OK: Extra external deps (if really needed)
+  external: ['special-native-module'],
+
+  dts: true, // ✅ Always required
+});
+```
+
+**NOT allowed:**
+
+```typescript
+// ❌ WRONG: Don't override preset settings
+export default defineConfig({
+  format: ['esm'],        // Already in preset!
+  target: 'es2022',       // Already in preset!
+  sourcemap: true,        // Already in preset!
+  // ...
+});
+
+// ❌ WRONG: Don't disable types
+dts: false,
+
+// ❌ WRONG: Don't duplicate external deps
+external: [
+  '@kb-labs/core',  // Already in preset!
+  '@kb-labs/cli',   // Already in preset!
+],
+```
+
+### eslint.config.js
+
+**Allowed customizations:**
+
+```javascript
+export default [
+  ...nodePreset,
+  {
+    // ✅ OK: Project-specific ignores only
+    ignores: ['**/*.generated.ts']
+  }
+];
+```
+
+**NOT allowed:**
+
+```javascript
+// ❌ WRONG: Don't duplicate preset ignores
+export default [
+  ...nodePreset,
+  {
+    ignores: [
+      '**/dist/**',        // Already in preset!
+      '**/node_modules/**', // Already in preset!
+    ]
+  }
+];
+```
+
+### tsconfig.json & tsconfig.build.json
+
+**NOT customizable!**
+
+These files MUST remain identical to templates. All TypeScript configuration is standardized in DevKit presets.
+
+```json
+// ❌ WRONG: Don't override extends
+{
+  "extends": "./my-custom-base.json"
+}
+
+// ❌ WRONG: Don't add compilerOptions
+{
+  "extends": "@kb-labs/devkit/tsconfig/node.json",
+  "compilerOptions": {
+    "strict": false  // Don't override preset!
+  }
+}
+```
+
+## 🔍 Drift Detection
+
+DevKit automatically detects configuration drift:
+
+```bash
+# Check all packages
+npx kb-devkit-check-configs
+
+# Check specific package
+npx kb-devkit-check-configs --package=@kb-labs/core
+
+# Auto-fix (creates backup)
+npx kb-devkit-check-configs --fix
+
+# CI mode (fail on drift)
+npx kb-devkit-check-configs --ci
+```
+
+### Drift Detection Rules
+
+| Issue | Severity | Auto-fix |
+|-------|----------|----------|
+| Missing `dts: true` | 🔴 Error | ✅ Yes |
+| Using `dts: false` | 🔴 Error | ✅ Yes |
+| Not using `nodePreset` | 🔴 Error | ⚠️ Manual |
+| Duplicate `external` | 🟡 Warning | ✅ Yes |
+| Duplicate `ignores` | 🟡 Warning | ✅ Yes |
+| Missing templates | 🔴 Error | ✅ Yes |
+| Modified templates | 🔴 Error | ⚠️ Manual |
+
+## 📚 Examples
+
+### ✅ Good Example (Minimal Package)
+
+```typescript
+// tsup.config.ts
+import { defineConfig } from 'tsup';
+import nodePreset from '@kb-labs/devkit/tsup/node.js';
+
+export default defineConfig({
+  ...nodePreset,
+  tsconfig: 'tsconfig.build.json',
+  entry: ['src/index.ts'],
+  dts: true,
+});
+```
+
+### ✅ Good Example (CLI Package with Multiple Entries)
+
+```typescript
+// tsup.config.ts
+import { defineConfig } from 'tsup';
+import nodePreset from '@kb-labs/devkit/tsup/node.js';
+
+export default defineConfig({
+  ...nodePreset,
+  tsconfig: 'tsconfig.build.json',
+  entry: [
+    'src/index.ts',
+    'src/cli/index.ts',
+    'src/cli/commands/build.ts',
+    'src/cli/commands/test.ts',
+  ],
+  dts: true,
+});
+```
+
+### ❌ Bad Example (Over-configured)
+
+```typescript
+// tsup.config.ts
+import { defineConfig } from 'tsup';
+
+// ❌ Not using preset!
+export default defineConfig({
+  format: ['esm'],
+  target: 'es2022',
+  sourcemap: true,
+  clean: true,
+  dts: true,
+  entry: ['src/index.ts'],
+  external: [/^@kb-labs\/.*/],  // Manual external
+});
+```
+
+## 🚀 Migration Guide
+
+### From Custom Config to Standard Template
+
+1. **Backup your current config**
+   ```bash
+   cp tsup.config.ts tsup.config.ts.backup
+   ```
+
+2. **Copy standard template**
+   ```bash
+   cp kb-labs-devkit/templates/configs/tsup.config.ts .
+   ```
+
+3. **Migrate customizations** (only if needed)
+   - Compare your backup with template
+   - Extract only truly necessary customizations
+   - Add them with comments explaining why
+
+4. **Test build**
+   ```bash
+   pnpm run build
+   ```
+
+5. **Verify types**
+   ```bash
+   npx kb-devkit-check-types
+   ```
+
+## 🔗 Related
+
+- [DevKit README](../../README.md)
+- [DevKit Usage Guide](../../USAGE_GUIDE.md)
+- [ADR-0009: Unified Build Convention](../../docs/adr/0009-unified-build-convention.md)

package/templates/configs/eslint.config.js

@@ -0,0 +1,27 @@
+/**
+ * Standard ESLint configuration template
+ *
+ * This is the canonical template for all @kb-labs packages.
+ * DO NOT modify this file locally - it is synced from @kb-labs/devkit
+ *
+ * Customization guidelines:
+ * - DevKit preset already includes all standard ignores
+ * - Only add project-specific ignores if absolutely necessary
+ * - Document why custom ignores are needed
+ *
+ * @see https://github.com/kb-labs/devkit#eslint-configuration
+ */
+import nodePreset from '@kb-labs/devkit/eslint/node.js';
+
+export default [
+  ...nodePreset,
+
+  // OPTIONAL: Add project-specific ignores only if needed
+  // DevKit preset already ignores: dist/, coverage/, node_modules/, *.d.ts, scripts/, etc.
+  // {
+  //   ignores: [
+  //     // Add ONLY project-specific patterns here
+  //     // Example: '**/*.generated.ts',
+  //   ]
+  // }
+];

package/templates/configs/package.json.bin

@@ -0,0 +1,25 @@
+{
+  "name": "@kb-labs/your-package",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Your package description",
+  "bin": {
+    "your-cli": "./dist/bin.cjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint .",
+    "test": "vitest"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@kb-labs/devkit": "workspace:*",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}

package/templates/configs/package.json.lib

@@ -0,0 +1,30 @@
+{
+  "name": "@kb-labs/your-package",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Your package description",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint .",
+    "test": "vitest"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@kb-labs/devkit": "workspace:*",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}

package/templates/configs/tsconfig.build.json

@@ -0,0 +1,15 @@
+{
+  "extends": "@kb-labs/devkit/tsconfig/node.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "baseUrl": ".",
+    "paths": {}
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "dist",
+    "node_modules"
+  ]
+}

package/templates/configs/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@kb-labs/devkit/tsconfig/node.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}

package/templates/configs/tsup.config.bin.ts

@@ -0,0 +1,34 @@
+/**
+ * Standard tsup configuration template for CLI binaries
+ *
+ * This template is for packages that provide executable binaries.
+ * Examples: cli-bin, core-state-daemon, any standalone executables
+ *
+ * DO NOT modify this file locally - it is synced from @kb-labs/devkit
+ *
+ * Key differences from library template:
+ * - Uses binPreset instead of nodePreset
+ * - Bundles ALL dependencies into standalone executable
+ * - Outputs .cjs format (CommonJS)
+ * - No type generation (dts: false)
+ * - Adds shebang automatically
+ *
+ * @see https://github.com/kb-labs/devkit#binary-packages
+ */
+import { defineConfig } from 'tsup';
+import binPreset from '@kb-labs/devkit/tsup/bin.js';
+
+export default defineConfig({
+  ...binPreset,
+
+  // REQUIRED: Use build-specific tsconfig (convention)
+  tsconfig: 'tsconfig.build.json',
+
+  // REQUIRED: Entry point for binary
+  // Output will be dist/bin.cjs
+  entry: { bin: 'src/bin.ts' },
+
+  // binPreset already sets dts: false (binaries don't need types)
+  // binPreset already adds shebang banner
+  // binPreset already bundles everything
+});

package/templates/configs/tsup.config.cli.ts

@@ -0,0 +1,41 @@
+/**
+ * Standard tsup configuration template for CLI packages
+ *
+ * This template is for CLI packages that provide:
+ * - Multiple command handlers as separate entries
+ * - Importable from other packages (not bundled)
+ *
+ * Examples: cli-commands, mind-cli, workflow-cli
+ *
+ * DO NOT modify this file locally - it is synced from @kb-labs/devkit
+ *
+ * Key differences:
+ * - Multiple entry points for commands
+ * - NOT bundled (uses nodePreset)
+ * - Generates types (for other packages to import)
+ *
+ * @see https://github.com/kb-labs/devkit#cli-packages
+ */
+import { defineConfig } from 'tsup';
+import nodePreset from '@kb-labs/devkit/tsup/node.js';
+
+export default defineConfig({
+  ...nodePreset,
+
+  // REQUIRED: Use build-specific tsconfig (convention)
+  tsconfig: 'tsconfig.build.json',
+
+  // REQUIRED: Multiple entries for CLI commands
+  entry: [
+    'src/index.ts', // Main export
+    'src/commands/**/*.ts', // All command files
+    // Add more entries as needed
+  ],
+
+  // REQUIRED: Explicit type generation
+  dts: true,
+
+  // OPTIONAL: CLI packages often have manifest files
+  // If you have manifest.json or similar, you might need to copy it:
+  // onSuccess: 'cp src/manifest.json dist/'
+});

package/templates/configs/tsup.config.dual.ts

@@ -0,0 +1,46 @@
+/**
+ * Standard tsup configuration template for packages with BOTH library AND binary
+ *
+ * This template is for packages that provide:
+ * 1. A library (importable by other packages)
+ * 2. A CLI binary (executable)
+ *
+ * Examples: cli packages with both API and bin
+ *
+ * DO NOT modify this file locally - it is synced from @kb-labs/devkit
+ *
+ * Important: This builds BOTH lib and bin in one config.
+ * For complex cases, use separate configs (tsup.lib.config.ts + tsup.bin.config.ts)
+ *
+ * @see https://github.com/kb-labs/devkit#dual-packages
+ */
+import { defineConfig } from 'tsup';
+import nodePreset from '@kb-labs/devkit/tsup/node.js';
+
+export default defineConfig([
+  // Library build (for imports)
+  {
+    ...nodePreset,
+    tsconfig: 'tsconfig.build.json',
+    entry: ['src/index.ts'], // Main library entry
+    dts: true,
+  },
+  // Binary build (for execution)
+  {
+    format: ['cjs'],
+    target: 'es2022',
+    platform: 'node',
+    sourcemap: true,
+    clean: false, // Already cleaned by first build
+    dts: false,
+    treeshake: true,
+    minify: false,
+    outDir: 'dist',
+    splitting: false,
+    noExternal: [/.*/], // Bundle everything
+    external: ['fsevents'], // Except native modules
+    banner: { js: '#!/usr/bin/env node' },
+    tsconfig: 'tsconfig.build.json',
+    entry: { bin: 'src/bin.ts' }, // Binary entry
+  },
+]);

package/templates/configs/tsup.config.ts

@@ -0,0 +1,36 @@
+/**
+ * Standard tsup configuration template
+ *
+ * This is the canonical template for all @kb-labs packages.
+ * DO NOT modify this file locally - it is synced from @kb-labs/devkit
+ *
+ * Customization guidelines:
+ * - For single entry point: use as-is
+ * - For multiple entry points: override `entry` array
+ * - For extra external deps: extend `external` array (only if needed!)
+ * - For special build needs: add minimal overrides, document why
+ *
+ * @see https://github.com/kb-labs/devkit#tsup-configuration
+ */
+import { defineConfig } from 'tsup';
+import nodePreset from '@kb-labs/devkit/tsup/node.js';
+
+export default defineConfig({
+  ...nodePreset,
+
+  // REQUIRED: Use build-specific tsconfig (convention)
+  tsconfig: 'tsconfig.build.json',
+
+  // REQUIRED: Entry point(s)
+  // Single entry (most common):
+  entry: ['src/index.ts'],
+  // Multiple entries (if needed):
+  // entry: ['src/index.ts', 'src/cli/index.ts', 'src/api/index.ts'],
+
+  // REQUIRED: Explicit type generation
+  dts: true,
+
+  // OPTIONAL: Only add if you need EXTRA externals beyond nodePreset
+  // nodePreset already includes all @kb-labs/* packages + dependencies from package.json
+  // external: ['special-package-not-in-preset'],
+});