@kb-labs/devkit 1.0.0

package/tsup/dual.js

@@ -0,0 +1,155 @@
+import { defineConfig } from 'tsup'
+import { readTsupExternalSync } from './external-sync.mjs'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * Dual Build Preset (ESM + CJS)
+ *
+ * ## Overview
+ *
+ * This preset builds BOTH ESM and CJS formats for maximum compatibility.
+ * Use this for libraries that need to support both modern ESM imports
+ * and legacy CJS requires (e.g., when bundling with tools like esbuild/rollup).
+ *
+ * ## Features
+ *
+ * - **Format**: ESM + CJS (dual exports)
+ * - **Output**: dist/index.js (ESM) + dist/index.cjs (CJS)
+ * - **Types**: dist/index.d.ts (shared for both formats)
+ * - **Externals**: All workspace packages + node_modules
+ * - **Tree-shaking**: Enabled
+ *
+ * ## When to use
+ *
+ * ✅ **Use for:**
+ * - Core libraries used by CLI binaries (core-runtime, core-sys, etc.)
+ * - Shared utilities that might be bundled by build tools
+ * - Packages that need to work in both ESM and CJS environments
+ * - Any library that might be consumed by bundlers (esbuild, rollup, webpack)
+ *
+ * ❌ **DO NOT use for:**
+ * - CLI binaries (use tsup/bin.js instead)
+ * - Pure ESM-only packages (use tsup/node.js instead)
+ * - React libraries (use tsup/react-lib.js instead)
+ *
+ * ## Package.json Setup
+ *
+ * Update your package.json with dual exports:
+ *
+ * ```json
+ * {
+ *   "type": "module",
+ *   "main": "./dist/index.cjs",
+ *   "module": "./dist/index.js",
+ *   "types": "./dist/index.d.ts",
+ *   "exports": {
+ *     ".": {
+ *       "import": "./dist/index.js",
+ *       "require": "./dist/index.cjs",
+ *       "types": "./dist/index.d.ts"
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ## Basic Example
+ *
+ * ```typescript
+ * // tsup.config.ts
+ * import { defineConfig } from 'tsup';
+ * import dualPreset from '@kb-labs/devkit/tsup/dual.js';
+ *
+ * export default defineConfig({
+ *   ...dualPreset,
+ *   entry: { index: 'src/index.ts' },
+ * });
+ * ```
+ *
+ * ## Multi-Entry Example
+ *
+ * ```typescript
+ * // tsup.config.ts
+ * import { defineConfig } from 'tsup';
+ * import dualPreset from '@kb-labs/devkit/tsup/dual.js';
+ *
+ * export default defineConfig({
+ *   ...dualPreset,
+ *   entry: {
+ *     index: 'src/index.ts',
+ *     utils: 'src/utils.ts',
+ *     helpers: 'src/helpers.ts',
+ *   },
+ * });
+ * ```
+ *
+ * ## Bundle Size Impact
+ *
+ * - Dual format roughly doubles the dist/ size (ESM + CJS)
+ * - Types (.d.ts) are shared between both formats
+ * - Example: ESM (50KB) + CJS (50KB) + Types (10KB) = 110KB total
+ *
+ * ## Why Dual Build?
+ *
+ * - **ESM**: Modern Node.js, better tree-shaking, top-level await
+ * - **CJS**: Legacy bundlers, better compatibility, easier to bundle
+ * - **Both**: Maximum compatibility across all environments
+ *
+ * ## Migration from ESM-only
+ *
+ * 1. Change import from `tsup/node.js` to `tsup/dual.js`
+ * 2. Update package.json exports (see example above)
+ * 3. Rebuild: `pnpm build`
+ * 4. Verify: Check dist/ has both .js (ESM) and .cjs (CJS)
+ */
+
+function resolveExternalDependencies() {
+  try {
+    const pkgPath = join(process.cwd(), 'package.json')
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+    const deps = Object.keys(pkg.dependencies ?? {})
+    const peerDeps = Object.keys(pkg.peerDependencies ?? {})
+    return Array.from(new Set([...deps, ...peerDeps]))
+  } catch {
+    return []
+  }
+}
+
+function getExternal() {
+  // Try to use generated tsup.external.json if available
+  try {
+    const generated = readTsupExternalSync()
+    if (generated.length > 0) {
+      return generated
+    }
+  } catch {
+    // If reading fails, fallback to package.json
+  }
+  // Fallback to reading package.json directly
+  return resolveExternalDependencies()
+}
+
+// Pre-compute external list once at module load time
+const externalList = getExternal()
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'], // ⬅️ Build both ESM and CJS
+  target: 'es2022',
+  sourcemap: true,
+  clean: true,
+  dts: true, // Generate .d.ts (shared for both formats)
+  treeshake: true,
+  minify: false,
+  outDir: 'dist',
+  splitting: false, // Disable splitting for better CJS compatibility
+  skipNodeModulesBundle: true,
+  shims: false,
+  // Mark all node_modules packages as external (including transitive deps)
+  noExternal: [],
+  external: [
+    /^[^./]|^\.[^./]|^\.\.[^/]/, // All node_modules packages (not relative paths)
+    ...externalList, // Explicitly listed packages (workspace + local deps)
+    /^@kb-labs\//, // Force all @kb-labs packages to be external
+  ],
+})

package/tsup/external-sync.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+
+/**
+ * Synchronously reads tsup.external.json and returns the externals array.
+ * Searches up the directory tree to find the file (similar to tsconfig.paths.json).
+ * This is a synchronous version for use in tsup.config.ts files.
+ *
+ * @param {string} [cwd] - Current working directory (defaults to process.cwd())
+ * @returns {string[]} Array of external package names
+ */
+export function readTsupExternalSync(cwd = process.cwd()) {
+  // Search up the directory tree for tsup.external.json
+  // Limit search to prevent infinite loops
+  let current = resolve(cwd);
+  let prev = null;
+  let depth = 0;
+  const maxDepth = 20; // Safety limit
+
+  while (current !== prev && depth < maxDepth) {
+    const externalPath = join(current, 'tsup.external.json');
+    if (existsSync(externalPath)) {
+      try {
+        const content = readFileSync(externalPath, 'utf8');
+        const data = JSON.parse(content);
+        return Array.isArray(data.externals) ? data.externals : [];
+      } catch {
+        // If file is invalid, continue searching up
+      }
+    }
+    prev = current;
+    current = dirname(current);
+    depth++;
+  }
+
+  // If file not found, return empty array
+  return [];
+}
+

package/tsup/external.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+
+import { dirname, resolve, join } from 'node:path';
+import { promises as fs } from 'node:fs';
+import process from 'node:process';
+import { glob } from 'glob';
+import { parse as parseYaml } from 'yaml';
+
+async function exists(path) {
+  try {
+    await fs.access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readJson(path) {
+  return JSON.parse(await fs.readFile(path, 'utf8'));
+}
+
+async function findWorkspaceConfigs(startDir) {
+  const roots = [];
+  let current = resolve(startDir);
+  let prev = null;
+  while (current !== prev) {
+    const wsFile = join(current, 'pnpm-workspace.yaml');
+    if (await exists(wsFile)) {
+      try {
+        const yaml = await fs.readFile(wsFile, 'utf8');
+        const data = parseYaml(yaml);
+        const patterns = Array.isArray(data?.packages) ? data.packages.filter(Boolean) : [];
+        roots.push({ dir: current, patterns });
+      } catch (error) {
+        // Silent fail in library mode
+      }
+    }
+    prev = current;
+    current = dirname(current);
+  }
+  return roots;
+}
+
+async function collectWorkspacePackages(workspaceRoots) {
+  const packages = new Set();
+  
+  for (const { dir, patterns } of workspaceRoots) {
+    for (const pattern of patterns) {
+      if (!pattern || typeof pattern !== 'string') {continue;}
+      const searchPattern = pattern.endsWith('/') ? `${pattern}package.json` : join(pattern, 'package.json');
+      const matches = await glob(searchPattern, {
+        cwd: dir,
+        dot: false,
+        nodir: true,
+        ignore: ['**/node_modules/**', '**/dist/**'],
+      });
+      for (const match of matches) {
+        try {
+          const pkgPath = resolve(dir, match);
+          const pkg = await readJson(pkgPath);
+          if (!pkg?.name || typeof pkg.name !== 'string') {continue;}
+          if (!pkg.name.startsWith('@kb-labs/')) {continue;}
+          packages.add(pkg.name);
+        } catch {
+          // Silent fail
+        }
+      }
+    }
+  }
+  
+  return Array.from(packages).sort();
+}
+
+/**
+ * Resolves external dependencies for tsup bundling.
+ * Returns an array of package names that should be marked as external:
+ * - All @kb-labs/* workspace packages
+ * - All dependencies and peerDependencies from the current package.json
+ * 
+ * @param {string} [cwd] - Current working directory (defaults to process.cwd())
+ * @returns {Promise<string[]>} Array of external package names
+ */
+export async function resolveTsupExternal(cwd = process.cwd()) {
+  const workspaceRoots = await findWorkspaceConfigs(cwd);
+  if (!workspaceRoots.length) {
+    return [];
+  }
+
+  const workspacePackages = await collectWorkspacePackages(workspaceRoots);
+  
+  // Also include dependencies from current package.json
+  const pkgPath = join(cwd, 'package.json');
+  let localDeps = [];
+  if (await exists(pkgPath)) {
+    try {
+      const pkg = await readJson(pkgPath);
+      const deps = Object.keys(pkg.dependencies ?? {});
+      const peerDeps = Object.keys(pkg.peerDependencies ?? {});
+      localDeps = Array.from(new Set([...deps, ...peerDeps]));
+    } catch {
+      // Silent fail
+    }
+  }
+  
+  // Combine workspace packages and local dependencies, remove duplicates
+  return Array.from(new Set([...workspacePackages, ...localDeps])).sort();
+}
+
+

package/tsup/node.js

@@ -0,0 +1,65 @@
+import { defineConfig } from 'tsup'
+import { readTsupExternalSync } from './external-sync.mjs'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+function resolveExternalDependencies() {
+  try {
+    const pkgPath = join(process.cwd(), 'package.json')
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+    const deps = Object.keys(pkg.dependencies ?? {})
+    const peerDeps = Object.keys(pkg.peerDependencies ?? {})
+    return Array.from(new Set([...deps, ...peerDeps]))
+  } catch {
+    return []
+  }
+}
+
+function getExternal() {
+  // Try to use generated tsup.external.json if available
+  // This file should be generated by kb-devkit-tsup-external and contains:
+  // - All @kb-labs/* workspace packages (found via pnpm-workspace.yaml)
+  // - All dependencies and peerDependencies from package.json
+  try {
+    const generated = readTsupExternalSync()
+    if (generated.length > 0) {
+      return generated
+    }
+  } catch {
+    // If reading fails, fallback to package.json
+  }
+  // Fallback to reading package.json directly
+  return resolveExternalDependencies()
+}
+
+// Pre-compute external list once at module load time
+const externalList = getExternal()
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  target: 'es2022',
+  sourcemap: true,
+  clean: true,
+  dts: true,
+  treeshake: true,
+  minify: false,
+  outDir: 'dist',
+  splitting: false,
+  skipNodeModulesBundle: true,
+  shims: false,
+  // Mark all node_modules packages as external (including transitive deps)
+  // Use noExternal: [] to prevent bundling any node_modules packages
+  // This is more reliable than regex for ensuring transitive deps stay external
+  noExternal: [],
+  external: [
+    /^[^./]|^\.[^./]|^\.\.[^/]/, // All node_modules packages (not relative paths)
+    // All workspace packages from tsup.external.json (generated by kb-devkit-tsup-external)
+    // This includes all @kb-labs/* packages found in pnpm-workspace.yaml
+    // plus dependencies/peerDependencies from package.json
+    ...externalList, // Explicitly listed packages (workspace + local deps)
+    // Force all @kb-labs packages to be external
+    // This catches packages linked via "link:" protocol that might not be in the workspace scan
+    /^@kb-labs\//,
+  ],
+})

package/tsup/react-lib.js

@@ -0,0 +1,18 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  target: 'es2022',
+  jsx: 'preserve',
+  sourcemap: true,
+  clean: true,
+  dts: true,
+  treeshake: true,
+  minify: false,
+  outDir: 'dist',
+  splitting: false,
+  skipNodeModulesBundle: true,
+  shims: false
+})
+

package/tsup/sdk.js

@@ -0,0 +1,118 @@
+import { defineConfig } from 'tsup';
+
+/**
+ * Preset for SDK/facade builds.
+ *
+ * ## Overview
+ *
+ * This preset bundles ALL @kb-labs/* workspace packages into a single
+ * self-contained SDK package. Consumers only need `@kb-labs/sdk` as dependency.
+ *
+ * ## Features
+ *
+ * - **Format**: ESM (modern, tree-shakeable)
+ * - **Bundling**: ALL @kb-labs/* packages included
+ * - **Externals**: Node.js built-ins + problematic CJS packages (execa, cross-spawn)
+ * - **Types**: Full .d.ts generation
+ * - **Multiple entry points**: Supports cli, helpers, manifest, etc.
+ *
+ * ## When to use
+ *
+ * ✅ **Use for:**
+ * - SDK packages that re-export from multiple workspace packages
+ * - Facade packages that need to be self-contained
+ * - Packages where consumers shouldn't need to install transitive deps
+ *
+ * ❌ **DO NOT use for:**
+ * - Regular libraries (use tsup/node.js instead)
+ * - Binaries (use tsup/bin.js instead)
+ * - Packages that should keep workspace deps as peer deps
+ *
+ * ## Example
+ *
+ * ```typescript
+ * import { defineConfig } from 'tsup';
+ * import sdkPreset from '@kb-labs/devkit/tsup/sdk.js';
+ *
+ * export default defineConfig({
+ *   ...sdkPreset,
+ *   tsconfig: 'tsconfig.build.json',
+ *   entry: [
+ *     'src/index.ts',
+ *     'src/cli.ts',
+ *     'src/helpers.ts',
+ *   ],
+ * });
+ * ```
+ *
+ * ## Bundle Size
+ *
+ * Expect 500KB-2MB per entry point depending on how much is imported.
+ * This is normal for self-contained SDK packages.
+ */
+
+// List of Node.js built-in modules (without node: prefix)
+const NODE_BUILTINS = [
+  'assert', 'async_hooks', 'buffer', 'child_process', 'cluster', 'console',
+  'constants', 'crypto', 'dgram', 'diagnostics_channel', 'dns', 'domain',
+  'events', 'fs', 'http', 'http2', 'https', 'inspector', 'module', 'net',
+  'os', 'path', 'perf_hooks', 'process', 'punycode', 'querystring', 'readline',
+  'repl', 'stream', 'string_decoder', 'sys', 'timers', 'tls', 'trace_events',
+  'tty', 'url', 'util', 'v8', 'vm', 'wasi', 'worker_threads', 'zlib',
+];
+
+// CJS packages that use dynamic require and can't be bundled into ESM
+// These must remain external and be installed as dependencies
+const PROBLEMATIC_CJS_PACKAGES = [
+  'execa',
+  'cross-spawn',
+  'glob',
+  'minimatch',
+  'fast-glob',
+  'globby',
+  'picomatch',
+  'micromatch',
+  'better-sqlite3',
+  'sharp',
+  'esbuild',
+  'yaml', // Uses require('process') internally
+];
+
+export default defineConfig({
+  format: ['esm'],
+  target: 'es2022',
+  platform: 'node',
+  sourcemap: true,
+  clean: true,
+  dts: true,
+  treeshake: true,
+  minify: false,
+  outDir: 'dist',
+  splitting: false,
+
+  // Bundle @kb-labs/* workspace packages, but NOT problematic CJS packages
+  noExternal: [/^@kb-labs\//],
+
+  // esbuild plugin to mark Node.js built-ins as external
+  esbuildPlugins: [
+    {
+      name: 'node-builtins-external',
+      setup(build) {
+        // Match Node.js built-ins with or without node: prefix, including subpaths
+        const builtinRegex = new RegExp(`^(node:)?(${NODE_BUILTINS.join('|')})(\\/.*)?$`);
+
+        build.onResolve({ filter: builtinRegex }, (args) => {
+          return { path: args.path, external: true };
+        });
+      },
+    },
+  ],
+
+  // Externalize: Node.js built-ins, native modules, and problematic CJS packages
+  external: [
+    // Native modules that can't be bundled
+    'fsevents',
+    // CJS packages with dynamic require
+    ...PROBLEMATIC_CJS_PACKAGES,
+  ],
+});

package/vite/react-app.js

@@ -0,0 +1,50 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import path from 'path'
+
+/**
+ * Vite config factory for React SPA applications
+ * @param {object} options - Configuration options
+ * @param {string} [options.entry='index.html'] - Entry HTML file
+ * @param {string} [options.outDir='dist'] - Output directory
+ * @returns {import('vite').UserConfig} Vite configuration
+ */
+export default function createReactAppConfig(options = {}) {
+  const {
+    entry = 'index.html',
+    outDir = 'dist',
+    root = process.cwd(),
+  } = options
+
+  return defineConfig({
+    root,
+    publicDir: 'public',
+    build: {
+      outDir,
+      sourcemap: true,
+      minify: false,
+      target: 'es2022',
+    },
+    plugins: [
+      react({
+        jsxRuntime: 'automatic',
+      }),
+    ],
+    resolve: {
+      alias: {
+        '@': path.resolve(root, 'src'),
+      },
+    },
+    server: {
+      port: 3000,
+      open: false,
+    },
+    preview: {
+      port: 3000,
+    },
+  })
+}
+
+// Export a default config for convenience
+export { defineConfig }
+

package/vitest/node.js

@@ -0,0 +1,37 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    globals: false,
+    reporters: ['default'],
+    include: ['**/*.{test,spec}.?(c|m)[jt]s?(x)'],
+    exclude: [
+      '**/node_modules/**',
+      '**/dist/**',
+      '**/cypress/**',
+      '**/.{idea,git,cache,output,temp}/**'
+    ],
+    coverage: {
+      enabled: false,
+      provider: 'v8',
+      all: true,
+      reportsDirectory: './coverage',
+      reporter: ['text', 'html', 'lcov'],
+      exclude: [
+        '**/node_modules/**',
+        '**/dist/**',
+        '**/__tests__/**',
+        '**/*.d.ts',
+        '**/types.ts',
+        '**/types/**'
+      ],
+      thresholds: {
+        statements: 90,
+        branches: 85,
+        functions: 90,
+        lines: 90
+      }
+    }
+  }
+})

package/vitest/react.js

@@ -0,0 +1,39 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    environment: 'jsdom',
+    globals: false,
+    reporters: ['default'],
+    include: ['**/*.{test,spec}.?(c|m)[jt]s?(x)'],
+    exclude: [
+      '**/node_modules/**',
+      '**/dist/**',
+      '**/cypress/**',
+      '**/.{idea,git,cache,output,temp}/**'
+    ],
+    setupFiles: ['./vitest-setup.ts'],
+    coverage: {
+      enabled: false,
+      provider: 'v8',
+      all: true,
+      reportsDirectory: './coverage',
+      reporter: ['text', 'html', 'lcov'],
+      exclude: [
+        '**/node_modules/**',
+        '**/dist/**',
+        '**/__tests__/**',
+        '**/*.d.ts',
+        '**/types.ts',
+        '**/types/**'
+      ],
+      thresholds: {
+        statements: 90,
+        branches: 85,
+        functions: 90,
+        lines: 90
+      }
+    }
+  }
+})
+

package/vitest/vitest-setup.ts

@@ -0,0 +1,9 @@
+// Vitest setup file for React testing
+import { afterEach } from 'vitest'
+import { cleanup } from '@testing-library/react'
+
+// Cleanup after each test
+afterEach(() => {
+  cleanup()
+})
+