workspace-utils 1.0.0

package/docs/src/troubleshooting.md

@@ -0,0 +1,533 @@
+# Troubleshooting
+
+This page covers common issues you might encounter when using workspace-utils and how to resolve them.
+
+## Installation Issues
+
+### Package Not Found
+
+If you get errors about workspace-utils not being found:
+
+```bash
+# Check if it's installed
+npm ls workspace-utils
+
+# If not installed, add it as a dev dependency
+npm install --save-dev workspace-utils
+
+# Verify it's in your package.json
+cat package.json | grep workspace-utils
+```
+
+### Permission Errors
+
+If you encounter permission errors:
+
+```bash
+# Clear npm cache
+npm cache clean --force
+
+# Remove node_modules and reinstall
+rm -rf node_modules package-lock.json
+npm install
+```
+
+### Version Conflicts
+
+If you have conflicting versions:
+
+```bash
+# Check installed version
+npm ls workspace-utils
+
+# Update to latest version
+npm install --save-dev workspace-utils@latest
+```
+
+## Workspace Detection Issues
+
+### No Workspace Found
+
+If workspace-utils can't detect your workspace:
+
+**Error:** `No workspace configuration found`
+
+**Solution:** Ensure you have one of these files in your root:
+
+- `pnpm-workspace.yaml` (for pnpm)
+- `package.json` with `workspaces` field (for npm/Bun)
+
+**Example for pnpm:**
+
+```yaml
+# pnpm-workspace.yaml
+packages:
+  - 'packages/*'
+  - 'apps/*'
+```
+
+**Example for npm/Bun:**
+
+```json
+{
+	"workspaces": ["packages/*", "apps/*"]
+}
+```
+
+### Mixed Package Managers
+
+If you have multiple lock files:
+
+**Error:** `Multiple package managers detected`
+
+**Solution:** Remove conflicting lock files:
+
+```bash
+# Keep only one lock file type
+rm package-lock.json yarn.lock  # Keep pnpm-lock.yaml
+# OR
+rm pnpm-lock.yaml yarn.lock      # Keep package-lock.json
+# OR
+rm pnpm-lock.yaml package-lock.json  # Keep yarn.lock
+```
+
+### Wrong Package Manager Detected
+
+If the wrong package manager is detected:
+
+**Check detection logic:**
+
+1. Bun: `bun.lockb` exists
+2. pnpm: `pnpm-lock.yaml` or `pnpm-workspace.yaml` exists
+3. npm: `package-lock.json` exists
+
+**Solution:** Remove unwanted lock files or use the correct package manager for your setup.
+
+## Script Execution Issues
+
+### No Packages Found with Script
+
+If you get `No packages found with the "script-name" script`:
+
+**Check which packages have the script:**
+
+```bash
+# Manually check package.json files
+find . -name "package.json" -not -path "./node_modules/*" -exec grep -l "script-name" {} \;
+```
+
+**Solution:** Add the script to package.json files where needed:
+
+```json
+{
+	"scripts": {
+		"test": "jest",
+		"build": "tsc",
+		"dev": "vite dev"
+	}
+}
+```
+
+### Scripts Failing
+
+If individual package scripts fail:
+
+**Debug a specific package:**
+
+```bash
+# Navigate to the failing package
+cd packages/failing-package
+
+# Run the script directly
+npm run script-name
+```
+
+**Common issues:**
+
+- Missing dependencies: `npm install`
+- TypeScript errors: Check `tsconfig.json`
+- Build output conflicts: `npm run clean` first
+
+### Permission Denied Errors
+
+If you get permission errors running scripts:
+
+```bash
+# On macOS/Linux, ensure scripts are executable
+find . -name "*.sh" -exec chmod +x {} \;
+
+# Check if using the right Node.js version
+node --version
+npm --version
+```
+
+## Build Issues
+
+### Dependency Cycle Detected
+
+If you get circular dependency errors:
+
+**Error:** `Dependency cycle detected: package-a -> package-b -> package-a`
+
+**Solution:** Review and break circular dependencies:
+
+1. Check `dependencies` and `devDependencies` in package.json files
+2. Consider extracting shared code to a separate package
+3. Use `peerDependencies` where appropriate
+
+**Debug dependency graph:**
+
+```bash
+# Create a simple script to visualize dependencies
+# deps.js
+const fs = require('fs');
+const path = require('path');
+
+// Find all package.json files and show dependencies
+// ... (custom script to analyze dependencies)
+```
+
+### Build Order Issues
+
+If builds fail due to missing dependencies:
+
+**Use `wsu build` instead of `wsu run build`:**
+
+```json
+{
+	"scripts": {
+		"build": "wsu build", // ✅ Dependency-aware
+		"build:parallel": "wsu run build" // ❌ May fail
+	}
+}
+```
+
+### Memory Issues During Build
+
+If builds run out of memory:
+
+```json
+{
+	"scripts": {
+		"build": "wsu build --concurrency 1",
+		"build:heavy": "NODE_OPTIONS='--max-old-space-size=4096' wsu build --concurrency 2"
+	}
+}
+```
+
+## Development Server Issues
+
+### Ports Already in Use
+
+If dev servers can't start due to port conflicts:
+
+**Check what's using ports:**
+
+```bash
+# On macOS/Linux
+lsof -i :3000
+lsof -i :4000
+
+# On Windows
+netstat -ano | findstr :3000
+```
+
+**Solution:** Kill conflicting processes or change ports in package.json:
+
+```json
+{
+	"scripts": {
+		"dev": "vite dev --port 3001"
+	}
+}
+```
+
+### Dev Servers Not Starting
+
+If development servers fail to start:
+
+**Check individual packages:**
+
+```bash
+cd packages/problematic-package
+npm run dev
+```
+
+**Common issues:**
+
+- Missing dev dependencies
+- Incorrect script configuration
+- Environment variable issues
+
+### Hot Reload Not Working
+
+If hot reload isn't working across packages:
+
+**Ensure proper file watching:**
+
+- Check if files are being watched correctly
+- Verify symlinks are set up properly
+- Check if your bundler supports monorepo setups
+
+## Performance Issues
+
+### Slow Execution
+
+If commands are running slowly:
+
+**Reduce concurrency:**
+
+```json
+{
+	"scripts": {
+		"test:slow": "wsu run test --concurrency 2",
+		"build:slow": "wsu build --concurrency 1"
+	}
+}
+```
+
+**Use filtering to run fewer packages:**
+
+```json
+{
+	"scripts": {
+		"test:changed": "wsu run test --filter 'packages/changed-*'",
+		"dev:minimal": "wsu dev --filter 'apps/main-app'"
+	}
+}
+```
+
+### High Memory Usage
+
+If workspace-utils uses too much memory:
+
+```bash
+# Monitor memory usage
+top -p $(pgrep -f workspace-utils)
+
+# Reduce concurrency
+# Add to package.json scripts
+"build:low-mem": "wsu build --concurrency 1"
+```
+
+## Character Encoding Issues
+
+### Garbled Characters in Output
+
+If you see strange characters instead of emojis:
+
+**Examples of issues:**
+
+```
+â Completed in 54428ms    # Should be ✅ or [OK]
+â±ï¸  Total build time    # Should be ⏱️ or [TIME]
+â ï¸ Warning message      # Should be ⚠️ or [WARN]
+```
+
+**Quick Solutions:**
+
+**Option 1: Force ASCII mode (recommended)**
+
+```json
+{
+	"scripts": {
+		"build": "wsu build --ascii",
+		"test": "wsu run test --ascii",
+		"dev": "wsu dev --ascii"
+	}
+}
+```
+
+**Option 2: Set environment variable**
+
+```bash
+# In your shell
+export WSU_ASCII=1
+
+# Or in package.json
+"build": "WSU_ASCII=1 wsu build"
+```
+
+**Option 3: Terminal fixes**
+If you prefer Unicode characters:
+
+1. Update your terminal to a modern version
+2. Set proper environment variables:
+   ```bash
+   export LANG=en_US.UTF-8
+   export LC_ALL=en_US.UTF-8
+   ```
+3. Force Unicode mode:
+   ```bash
+   export WSU_UNICODE=1
+   ```
+
+**Debug what's being detected:**
+
+```bash
+# Check your environment
+node -e "console.log(process.platform, process.env.TERM, process.env.TERM_PROGRAM)"
+```
+
+## Filtering Issues
+
+### Filter Not Matching Packages
+
+If `--filter` doesn't match expected packages:
+
+**Debug filtering:**
+
+```bash
+# List all packages first
+find . -name "package.json" -not -path "./node_modules/*" | head -10
+
+# Check package names in workspace
+```
+
+**Common filter patterns:**
+
+```json
+{
+	"scripts": {
+		"test:scope": "wsu run test --filter '@company/*'",
+		"test:apps": "wsu run test --filter 'apps/*'",
+		"test:utils": "wsu run test --filter '*-utils'",
+		"test:frontend": "wsu run test --filter '*frontend*'"
+	}
+}
+```
+
+### Case Sensitivity
+
+Filters are case-sensitive. Use exact casing:
+
+```json
+{
+	"scripts": {
+		"test:React": "wsu run test --filter '*React*'", // Correct
+		"test:react": "wsu run test --filter '*react*'" // Different results
+	}
+}
+```
+
+## Environment Issues
+
+### Node.js Version
+
+workspace-utils requires Node.js 18+:
+
+```bash
+# Check version
+node --version
+
+# If too old, update Node.js
+# Use nvm, fnm, or download from nodejs.org
+```
+
+### Environment Variables
+
+If environment variables aren't being passed:
+
+**In your package scripts:**
+
+```json
+{
+	"scripts": {
+		"test:env": "NODE_ENV=test wsu run test",
+		"build:prod": "NODE_ENV=production wsu build"
+	}
+}
+```
+
+**For complex environments, use .env files in individual packages.**
+
+## Getting Help
+
+### Enable Debug Mode
+
+If you need more information about what's happening:
+
+```json
+{
+	"scripts": {
+		"debug:build": "DEBUG=workspace-utils wsu build",
+		"debug:test": "DEBUG=* wsu run test"
+	}
+}
+```
+
+### Verbose Output
+
+For more detailed logging:
+
+```bash
+# Run with verbose npm logging
+npm run build --verbose
+
+# Check the exact commands being run
+```
+
+### Common Command Issues
+
+**Command not found:**
+
+```bash
+# Make sure workspace-utils is installed
+npm ls workspace-utils
+
+# Try running directly
+npx wsu --version
+```
+
+**Script syntax errors:**
+
+```json
+{
+	"scripts": {
+		// ❌ Wrong quotes
+		"test": "wsu run test",
+
+		// ✅ Correct quotes
+		"test": "wsu run test"
+	}
+}
+```
+
+## Reporting Issues
+
+If you encounter a bug or need help:
+
+1. **Check this troubleshooting guide first**
+2. **Search existing issues** in the repository
+3. **Provide minimal reproduction** when reporting:
+   - Your `package.json` scripts
+   - Workspace structure
+   - Full error message
+   - Node.js and package manager versions
+
+**Useful info to include:**
+
+```bash
+# System information
+node --version
+npm --version  # or pnpm --version, bun --version
+npx wsu --version
+
+# Workspace structure
+tree -I node_modules -L 3
+```
+
+## Quick Fixes Checklist
+
+When things go wrong, try these in order:
+
+1. **Check installation:** `npm ls workspace-utils`
+2. **Verify workspace setup:** Ensure workspace config files exist
+3. **Clean and reinstall:** `rm -rf node_modules && npm install`
+4. **Check package.json syntax:** Ensure scripts are properly quoted
+5. **Test individual packages:** `cd package && npm run script-name`
+6. **Reduce concurrency:** Add `--concurrency 1` to scripts
+7. **Check Node.js version:** `node --version` (should be 18+)
+8. **Clear caches:** `npm cache clean --force`
+
+Most issues are resolved by steps 1-4!

package/index.ts

@@ -0,0 +1,84 @@
+#!/usr/bin/env bun
+import { Command } from 'commander';
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { runCommand } from './src/commands/run.ts';
+import { buildCommand } from './src/commands/build.ts';
+import { devCommand } from './src/commands/dev.ts';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Read package.json for version by traversing up directories
+function findPackageJson(startDir: string): Record<string, unknown> {
+	let currentDir = startDir;
+	while (currentDir !== dirname(currentDir)) {
+		try {
+			const packageJsonPath = join(currentDir, 'package.json');
+			const content = readFileSync(packageJsonPath, 'utf8');
+			return JSON.parse(content) as Record<string, unknown>;
+		} catch {
+			currentDir = dirname(currentDir);
+		}
+	}
+	throw new Error('package.json not found in any parent directory');
+}
+
+const packageJson = findPackageJson(__dirname);
+
+const program = new Command();
+
+program
+	.name('workspace-utils')
+	.description('CLI tool to orchestrate scripts across monorepo workspaces (Bun, pnpm, npm)')
+	.version(packageJson.version as string)
+	.option('--ascii', 'Force ASCII output (no Unicode/emoji characters)', false);
+
+// Run command - execute a script across packages
+program
+	.command('run <script>')
+	.description('Run a script across multiple packages')
+	.option('-c, --concurrency <number>', 'Maximum number of concurrent processes', '4')
+	.option('-f, --filter <pattern>', 'Filter packages by pattern (e.g., @scope/*)')
+	.option('--sequential', 'Run scripts sequentially (default is parallel)', false)
+	.action((script, options) => {
+		if (program.opts().ascii) {
+			process.env.WSU_ASCII = '1';
+		}
+		return runCommand(script, options);
+	});
+
+// Build command - build packages in dependency order
+program
+	.command('build')
+	.description('Build packages in dependency order')
+	.option('-f, --filter <pattern>', 'Filter packages by pattern')
+	.option('-c, --concurrency <number>', 'Maximum number of concurrent builds', '4')
+	.option('--skip-unchanged', "Skip packages that haven't changed (future feature)", false)
+	.action(options => {
+		if (program.opts().ascii) {
+			process.env.WSU_ASCII = '1';
+		}
+		return buildCommand(options);
+	});
+
+// Dev command - run dev scripts in parallel with live logs
+program
+	.command('dev')
+	.description('Run dev scripts across packages with live log streaming')
+	.option('-f, --filter <pattern>', 'Filter packages by pattern')
+	.option('-c, --concurrency <number>', 'Maximum number of concurrent processes', '4')
+	.action(options => {
+		if (program.opts().ascii) {
+			process.env.WSU_ASCII = '1';
+		}
+		return devCommand(options);
+	});
+
+// Default to help if no command provided
+if (process.argv.length <= 2) {
+	program.help();
+}
+
+program.parse();

package/package.json

@@ -0,0 +1,54 @@
+{
+	"name": "workspace-utils",
+	"version": "1.0.0",
+	"description": "A CLI tool to orchestrate scripts across monorepo workspaces (Bun, pnpm, npm) with parallel execution and dependency-aware builds.",
+	"module": "index.ts",
+	"type": "module",
+	"bin": {
+		"workspace-utils": "./dist/index.js",
+		"wsu": "./dist/index.js"
+	},
+	"scripts": {
+		"build": "bun build index.ts --outdir dist --target node && cp package.json dist/",
+		"dev": "bun run index.ts",
+		"prepublishOnly": "bun run build",
+		"format": "prettier --write .",
+		"format:check": "prettier --check .",
+		"test": "bun test",
+		"test:watch": "bun test --watch",
+		"docs:build": "cd docs && mdbook build",
+		"docs:serve": "cd docs && mdbook serve",
+		"docs:watch": "cd docs && mdbook serve --open"
+	},
+	"keywords": [
+		"monorepo",
+		"workspaces",
+		"bun",
+		"pnpm",
+		"npm",
+		"cli",
+		"parallel",
+		"dependency-graph",
+		"build-orchestration"
+	],
+	"author": "",
+	"license": "MIT",
+	"dependencies": {
+		"commander": "^11.1.0",
+		"fast-glob": "^3.3.2",
+		"picocolors": "^1.0.0",
+		"yaml": "^2.8.1"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.2.20",
+		"@types/node": "^20.10.0",
+		"prettier": "^3.6.2"
+	},
+	"peerDependencies": {
+		"typescript": "^5"
+	},
+	"engines": {
+		"node": ">=18",
+		"bun": ">=1.0.0"
+	}
+}