workspace-utils 1.0.0

package/docs/src/commands/overview.md

@@ -0,0 +1,239 @@
+# Commands Overview
+
+workspace-utils provides three main commands designed to handle different aspects of monorepo workflow management. Each command is optimized for specific use cases while sharing common functionality like package filtering and concurrency control.
+
+## Command Summary
+
+| Command               | Purpose                                | Default Mode         | Use Case                       |
+| --------------------- | -------------------------------------- | -------------------- | ------------------------------ |
+| [`run`](./run.md)     | Execute scripts across packages        | **Parallel**         | Tests, linting, custom scripts |
+| [`build`](./build.md) | Build packages respecting dependencies | **Dependency order** | Production builds, CI/CD       |
+| [`dev`](./dev.md)     | Start development servers              | **Parallel**         | Local development              |
+
+## Quick Reference
+
+### wsu run
+
+```bash
+wsu run <script> [options]
+```
+
+Execute any script across multiple packages in parallel (by default) or sequentially.
+
+**Package.json setup:**
+
+```json
+{
+	"scripts": {
+		"test": "wsu run test",
+		"lint": "wsu run lint --sequential",
+		"typecheck": "wsu run typecheck --concurrency 8"
+	}
+}
+```
+
+**Usage:**
+
+```bash
+npm run test       # Run tests in parallel
+npm run lint       # Run linting sequentially
+npm run typecheck  # Custom concurrency
+```
+
+### wsu build
+
+```bash
+wsu build [options]
+```
+
+Build packages in dependency order using topological sorting. Packages are built in batches where each batch can run in parallel.
+
+**Package.json setup:**
+
+```json
+{
+	"scripts": {
+		"build": "wsu build",
+		"build:apps": "wsu build --filter 'apps/*'",
+		"build:slow": "wsu build --concurrency 2"
+	}
+}
+```
+
+**Usage:**
+
+```bash
+npm run build       # Build all packages
+npm run build:apps  # Build only apps
+npm run build:slow  # Limit batch concurrency
+```
+
+### wsu dev
+
+```bash
+wsu dev [options]
+```
+
+Start development servers with live log streaming. Designed for long-running processes with real-time output.
+
+**Package.json setup:**
+
+```json
+{
+	"scripts": {
+		"dev": "wsu dev",
+		"dev:scope": "wsu dev --filter '@scope/*'",
+		"dev:limited": "wsu dev --concurrency 3"
+	}
+}
+```
+
+**Usage:**
+
+```bash
+npm run dev         # Start all dev servers
+npm run dev:scope   # Start scoped packages
+npm run dev:limited # Limit concurrent servers
+```
+
+## Global Options
+
+All commands support these common options:
+
+### Filtering
+
+- `--filter <pattern>` - Filter packages using glob patterns
+- Examples: `"@scope/*"`, `"apps/*"`, `"*-utils"`, `"*frontend*"`
+
+### Concurrency
+
+- `--concurrency <number>` - Maximum concurrent processes (default: 4)
+- Applies to parallel execution and batch processing
+
+### Help
+
+- `--help` - Show command-specific help and options
+
+## Execution Modes
+
+### Parallel Execution
+
+**Used by:** `run` (default), `dev`
+**Behavior:** All matching packages execute simultaneously
+**Best for:** Tests, linting, development servers
+
+```bash
+npm run test  # with "test": "wsu run test" in package.json
+# ✅ Runs tests in all packages at the same time
+```
+
+### Sequential Execution
+
+**Used by:** `run` (with --sequential flag)
+**Behavior:** Packages execute one after another
+**Best for:** Resource-intensive tasks, ordered operations
+
+```bash
+npm run build:sequential  # with "build:sequential": "wsu run build --sequential"
+# ✅ Runs builds one package at a time
+```
+
+### Dependency-Aware Execution
+
+**Used by:** `build`
+**Behavior:** Packages are grouped into batches based on dependencies
+**Best for:** Building, publishing, dependency-critical operations
+
+```bash
+npm run build  # with "build": "wsu build" in package.json
+# ✅ Builds dependencies first, then dependents
+```
+
+## Package Manager Detection
+
+workspace-utils automatically detects your package manager:
+
+| Package Manager | Detection Criteria                                                |
+| --------------- | ----------------------------------------------------------------- |
+| **Bun**         | `bun.lockb`, `bunfig.toml`, or bun-specific `package.json` fields |
+| **pnpm**        | `pnpm-lock.yaml`, `pnpm-workspace.yaml`                           |
+| **npm**         | `package-lock.json`, `.npmrc`                                     |
+
+The detected package manager is used for all script execution (e.g., `bun run test`, `pnpm run test`, `npm run test`).
+
+## Error Handling
+
+### Exit Behavior
+
+- **Single failure in parallel mode:** Other packages continue running
+- **Single failure in sequential mode:** Execution stops immediately
+- **Single failure in build mode:** Current batch fails, subsequent batches are skipped
+
+### Exit Codes
+
+- `0` - All packages executed successfully
+- `1` - One or more packages failed
+- `2` - Configuration or setup error
+
+## Output Format
+
+All commands provide consistent, color-coded output:
+
+```
+🚀 Starting operation...
+📁 Workspace root: /path/to/workspace
+📦 Found X packages
+✅ Running "script" in Y packages
+🔧 Package manager: detected-pm
+⚡ Execution mode: parallel/sequential/dependency-order
+
+[package-1] Starting: pm run script
+[package-2] Starting: pm run script
+[package-1] ✅ Completed in 1,234ms
+[package-2] ❌ Failed with exit code 1
+
+📊 Execution Summary:
+✅ Successful: 1
+❌ Failed: 1
+⏱️  Total duration: 2,345ms
+```
+
+## Best Practices
+
+### Choose the Right Command
+
+- **`run`** for most script execution (tests, linting, utilities)
+- **`build`** when package dependencies matter
+- **`dev`** for long-running development processes
+
+### Use Filtering Effectively
+
+```json
+{
+	"scripts": {
+		"test:packages": "wsu run test --filter 'packages/*'",
+		"dev:apps": "wsu dev --filter 'apps/*'",
+		"build:company": "wsu build --filter '@company/*'"
+	}
+}
+```
+
+### Optimize Concurrency
+
+```json
+{
+	"scripts": {
+		"build:slow": "wsu run build --concurrency 2",
+		"test:fast": "wsu run test --concurrency 8",
+		"dev": "wsu dev --concurrency 4"
+	}
+}
+```
+
+## Next Steps
+
+Dive deeper into each command:
+
+- [**run command**](./run.md) - Detailed script execution options
+- [**build command**](./build.md) - Dependency-aware building
+- [**dev command**](./dev.md) - Development server management

package/docs/src/commands/run.md

@@ -0,0 +1,153 @@
+# run Command
+
+The `run` command executes scripts across multiple packages in your workspace, with parallel execution by default.
+
+## Recommended Usage
+
+Add to your `package.json` scripts:
+
+```json
+{
+	"scripts": {
+		"test": "wsu run test",
+		"lint": "wsu run lint",
+		"typecheck": "wsu run typecheck"
+	}
+}
+```
+
+Then run:
+
+```bash
+npm run test     # Run tests across packages
+npm run lint     # Run linting across packages
+npm run typecheck # Run type checking across packages
+```
+
+## Direct Usage (if needed)
+
+```bash
+wsu run <script> [options]
+```
+
+## Arguments
+
+- `<script>` - The npm script name to execute (e.g., `test`, `lint`, `build`)
+
+## Options
+
+| Option                   | Description                          | Default      |
+| ------------------------ | ------------------------------------ | ------------ |
+| `--filter <pattern>`     | Filter packages by glob pattern      | All packages |
+| `--concurrency <number>` | Max concurrent processes             | `4`          |
+| `--sequential`           | Run sequentially instead of parallel | `false`      |
+
+## Examples
+
+### Basic Usage
+
+Add scripts to your `package.json`:
+
+```json
+{
+	"scripts": {
+		"test": "wsu run test",
+		"test:sequential": "wsu run test --sequential",
+		"lint": "wsu run lint --concurrency 8"
+	}
+}
+```
+
+Then run:
+
+```bash
+npm run test            # Run tests in parallel (default)
+npm run test:sequential # Run tests sequentially
+npm run lint            # Run linting with custom concurrency
+```
+
+### Package Filtering
+
+Add filtered scripts to your `package.json`:
+
+```json
+{
+	"scripts": {
+		"test:company": "wsu run test --filter '@company/*'",
+		"dev:apps": "wsu run dev --filter 'apps/*'",
+		"build:backend": "wsu run build --filter '*backend*'"
+	}
+}
+```
+
+Then run:
+
+```bash
+npm run test:company   # Run tests for scoped packages
+npm run dev:apps       # Run dev scripts for apps only
+npm run build:backend  # Run builds for backend packages
+```
+
+### Example Output
+
+```
+🚀 Running script "test" across packages...
+
+📦 Found 3 packages
+✅ Running "test" in 3 packages:
+  • @company/utils
+  • @company/ui-components
+  • apps/web-app
+
+🔧 Package manager: pnpm
+⚡ Execution mode: parallel (concurrency: 4)
+
+[@company/utils] Starting: pnpm run test
+[@company/ui-components] Starting: pnpm run test
+[apps/web-app] Starting: pnpm run test
+[@company/utils] ✅ Completed in 1,234ms
+[@company/ui-components] ✅ Completed in 2,456ms
+[apps/web-app] ✅ Completed in 3,789ms
+
+📊 Execution Summary:
+✅ Successful: 3
+⏱️  Total duration: 3,789ms
+```
+
+## Execution Modes
+
+### Parallel (Default)
+
+- Runs all packages simultaneously
+- Faster for I/O bound tasks like tests and linting
+- Other packages continue if one fails
+
+### Sequential
+
+- Runs packages one at a time
+- Stops on first failure
+- Better for resource-intensive tasks
+
+## When to Use
+
+- **Tests** - Parallel execution for fast feedback
+- **Linting** - High concurrency for quick checks
+- **Type checking** - Parallel across packages
+- **Custom scripts** - Any script that exists in package.json
+
+## Package.json Integration
+
+Add common patterns to your root `package.json`:
+
+```json
+{
+	"scripts": {
+		"test": "wsu run test",
+		"test:watch": "wsu run test:watch",
+		"lint": "wsu run lint --concurrency 8",
+		"lint:fix": "wsu run lint:fix",
+		"typecheck": "wsu run typecheck",
+		"clean": "wsu run clean --sequential"
+	}
+}
+```

package/docs/src/configuration.md

@@ -0,0 +1,249 @@
+# Configuration
+
+workspace-utils is designed to work with **zero configuration** by default. It automatically detects your workspace setup and package manager, then runs with sensible defaults. However, you can customize behavior through command-line options.
+
+## No Configuration Files
+
+Unlike many other tools, workspace-utils **does not use configuration files**. All behavior is controlled through:
+
+1. **Command-line flags** (primary method)
+2. **Workspace structure** (automatic detection)
+3. **Package manager detection** (automatic)
+
+This approach keeps things simple and ensures your commands are explicit and reproducible.
+
+## Command-Line Configuration
+
+All configuration is done through command-line options. Here are the most commonly used options:
+
+### Global Options
+
+Available for all commands:
+
+| Option                   | Description                     | Default      | Example               |
+| ------------------------ | ------------------------------- | ------------ | --------------------- |
+| `--filter <pattern>`     | Filter packages by glob pattern | All packages | `--filter "@scope/*"` |
+| `--concurrency <number>` | Max concurrent processes        | `4`          | `--concurrency 8`     |
+| `--help`                 | Show command help               | -            | `--help`              |
+
+### Command-Specific Options
+
+#### run command
+
+```bash
+workspace-utils run <script> [options]
+```
+
+| Option         | Description                          | Default |
+| -------------- | ------------------------------------ | ------- |
+| `--sequential` | Run sequentially instead of parallel | `false` |
+
+#### build command
+
+```bash
+workspace-utils build [options]
+```
+
+| Option             | Description                      | Default |
+| ------------------ | -------------------------------- | ------- |
+| `--skip-unchanged` | Skip unchanged packages (future) | `false` |
+
+#### dev command
+
+```bash
+workspace-utils dev [options]
+```
+
+No additional options - uses global options only.
+
+## Environment Variables
+
+workspace-utils respects these environment variables:
+
+| Variable      | Description          | Default       |
+| ------------- | -------------------- | ------------- |
+| `NODE_ENV`    | Node environment     | `development` |
+| `FORCE_COLOR` | Force colored output | `1` (enabled) |
+
+## Package Manager Detection
+
+workspace-utils automatically detects your package manager based on lock files and configuration:
+
+### Detection Priority
+
+1. **Bun** - if `bun.lockb` exists or bun-specific fields in `package.json`
+2. **pnpm** - if `pnpm-lock.yaml` or `pnpm-workspace.yaml` exists
+3. **npm** - if `package-lock.json` exists
+
+### Workspace Configuration
+
+The tool reads workspace configuration from:
+
+| Package Manager | Configuration Source                     |
+| --------------- | ---------------------------------------- |
+| **Bun**         | `package.json` → `workspaces` field      |
+| **pnpm**        | `pnpm-workspace.yaml` → `packages` field |
+| **npm**         | `package.json` → `workspaces` field      |
+
+## Workspace Structure Requirements
+
+### Supported Workspace Formats
+
+#### Bun Workspaces
+
+```json
+{
+	"name": "my-monorepo",
+	"workspaces": ["packages/*", "apps/*"]
+}
+```
+
+#### pnpm Workspaces
+
+```yaml
+# pnpm-workspace.yaml
+packages:
+  - 'packages/*'
+  - 'apps/*'
+  - '!**/test/**'
+```
+
+#### npm Workspaces
+
+```json
+{
+	"name": "my-monorepo",
+	"workspaces": {
+		"packages": ["packages/*", "apps/*"]
+	}
+}
+```
+
+## Common Configuration Patterns
+
+### Package.json Scripts
+
+Add workspace-utils commands to your root `package.json`:
+
+```json
+{
+	"scripts": {
+		"test": "workspace-utils run test",
+		"test:sequential": "workspace-utils run test --sequential",
+		"build": "workspace-utils build",
+		"build:apps": "workspace-utils build --filter 'apps/*'",
+		"dev": "workspace-utils dev",
+		"lint": "workspace-utils run lint --concurrency 8",
+		"typecheck": "workspace-utils run typecheck --parallel"
+	}
+}
+```
+
+### CI/CD Configuration
+
+Optimize for continuous integration:
+
+```bash
+# Lower concurrency for CI resources
+workspace-utils run test --concurrency 2
+
+# Sequential builds for predictable resource usage
+workspace-utils build --concurrency 1
+
+# Parallel linting for speed
+workspace-utils run lint --concurrency 4
+```
+
+### Development Workflow
+
+Optimize for local development:
+
+```bash
+# Start all dev servers
+workspace-utils dev
+
+# Run tests with higher concurrency on powerful dev machines
+workspace-utils run test --concurrency 8
+
+# Filter to work on specific features
+workspace-utils dev --filter "*frontend*"
+```
+
+## Performance Tuning
+
+### Concurrency Guidelines
+
+| Task Type       | Recommended Concurrency | Reasoning                        |
+| --------------- | ----------------------- | -------------------------------- |
+| **Tests**       | 4-8                     | Usually I/O bound, can run many  |
+| **Builds**      | 2-4                     | CPU intensive, fewer parallel    |
+| **Linting**     | 6-12                    | Fast, lightweight processes      |
+| **Dev servers** | 2-6                     | Resource intensive, long-running |
+
+### System Resources
+
+Consider your system when setting concurrency:
+
+```bash
+# For 4-core machines
+workspace-utils run build --concurrency 2
+
+# For 8+ core machines
+workspace-utils run test --concurrency 8
+
+# For CI with limited resources
+workspace-utils run lint --concurrency 2
+```
+
+## Filtering Patterns
+
+### Glob Patterns
+
+workspace-utils supports standard glob patterns:
+
+| Pattern      | Matches                        | Example                             |
+| ------------ | ------------------------------ | ----------------------------------- |
+| `@scope/*`   | All packages in scope          | `@company/utils`, `@company/ui`     |
+| `apps/*`     | All packages in apps directory | `apps/web`, `apps/mobile`           |
+| `*-utils`    | Packages ending with -utils    | `date-utils`, `string-utils`        |
+| `*frontend*` | Packages containing frontend   | `my-frontend-app`, `frontend-utils` |
+
+### Multiple Filters
+
+Use multiple invocations for complex filtering:
+
+```bash
+# Run tests on backend packages only
+workspace-utils run test --filter "@company/backend-*"
+
+# Build all apps and shared libraries
+workspace-utils build --filter "apps/*"
+workspace-utils build --filter "@company/shared-*"
+```
+
+## Error Handling Configuration
+
+### Exit Behavior
+
+workspace-utils has different exit behaviors by command:
+
+| Command            | Failure Behavior                              |
+| ------------------ | --------------------------------------------- |
+| `run` (parallel)   | Continue other packages, exit 1 if any failed |
+| `run` (sequential) | Stop on first failure, exit with that code    |
+| `build`            | Stop current batch on failure, skip remaining |
+| `dev`              | Stop all servers on any failure               |
+
+### Error Codes
+
+| Exit Code | Meaning                                    |
+| --------- | ------------------------------------------ |
+| `0`       | All operations successful                  |
+| `1`       | One or more package operations failed      |
+| `2`       | Configuration or workspace detection error |
+
+## Next Steps
+
+- Learn about [Workspace Detection](./concepts/workspace-detection.md)
+- Explore [Package Manager Support](./concepts/package-managers.md)
+- See [Performance Tuning](./advanced/performance.md) for optimization tips