workspace-utils 1.0.0 → 1.0.2

package/docs/src/introduction.md

@@ -1,117 +0,0 @@
-# workspace-utils
-
-A powerful **CLI tool** designed to orchestrate scripts across monorepo workspaces with **parallel execution**, **dependency-aware builds**, and **real-time log streaming**.
-
-## What is workspace-utils?
-
-`workspace-utils` simplifies working with monorepos by providing intelligent script orchestration across multiple packages. Whether you're using **Bun**, **pnpm**, or **npm** workspaces, this tool automatically detects your setup and provides a unified interface for running scripts efficiently.
-
-## Key Features
-
-### 🚀 **Parallel Execution by Default**
-
-Run scripts across multiple packages simultaneously with configurable concurrency limits. Perfect for tests, linting, and development workflows.
-
-### 🏗️ **Dependency-Aware Builds**
-
-Automatically builds packages in the correct order using topological sorting. Dependencies are always built before their dependents.
-
-### 🎨 **Real-time Log Streaming**
-
-Color-coded, prefixed output makes it easy to track which package is doing what. Each package gets its own color for instant identification.
-
-### 🔍 **Smart Package Filtering**
-
-Use glob patterns to target specific packages:
-
-- `--filter "@scope/*"` - All packages in a scope
-- `--filter "apps/*"` - All apps
-- `--filter "*-utils"` - All utility packages
-
-### 📦 **Multi Package Manager Support**
-
-Works seamlessly with:
-
-- **Bun workspaces** (`package.json` + `bun.lockb`)
-- **pnpm workspaces** (`pnpm-workspace.yaml` + `pnpm-lock.yaml`)
-- **npm workspaces** (`package.json` + `package-lock.json`)
-
-### 🎯 **Zero Configuration**
-
-No config files needed. Just run it in any workspace and it automatically detects your setup.
-
-## Why workspace-utils?
-
-### Before workspace-utils
-
-```bash
-# Run tests manually in each package
-cd packages/utils && npm test
-cd ../ui-components && npm test
-cd ../api-client && npm test
-cd ../../apps/web-app && npm test
-
-# Build in correct order manually
-cd packages/utils && npm run build
-cd ../ui-components && npm run build  # depends on utils
-cd ../api-client && npm run build     # depends on utils
-cd ../../apps/web-app && npm run build # depends on ui-components & api-client
-```
-
-### After workspace-utils
-
-```json
-{
-	"scripts": {
-		"test": "wsu run test",
-		"build": "wsu build",
-		"dev": "wsu dev"
-	}
-}
-```
-
-```bash
-# Run all tests in parallel
-npm run test
-
-# Build everything in correct dependency order
-npm run build
-
-# Start all dev servers with live logs
-npm run dev
-```
-
-## At a Glance
-
-| Package.json Script      | Purpose                   | Execution                      |
-| ------------------------ | ------------------------- | ------------------------------ |
-| `"test": "wsu run test"` | Run tests across packages | **Parallel** by default        |
-| `"build": "wsu build"`   | Build packages            | **Dependency order** (batched) |
-| `"dev": "wsu dev"`       | Start dev servers         | **Parallel** with live logs    |
-
-## Quick Example
-
-Given this monorepo structure:
-
-```
-my-project/
-├── package.json (workspaces: ["packages/*", "apps/*"])
-├── packages/
-│   ├── utils/           # no dependencies
-│   ├── ui-components/   # depends on utils
-│   └── api-client/      # depends on utils
-└── apps/
-    └── web-app/         # depends on ui-components, api-client
-```
-
-Running `npm run build` (with `"build": "wsu build"` in package.json) will:
-
-1. **Batch 1:** Build `utils`
-2. **Batch 2:** Build `ui-components` and `api-client` in parallel
-3. **Batch 3:** Build `web-app`
-
-Running `npm run test` (with `"test": "wsu run test"` in package.json) will run all tests in parallel across all packages simultaneously.
-
-## Ready to Get Started?
-
-Continue to [Installation](./installation.md) to set up workspace-utils in your project.

package/docs/src/quick-start.md

@@ -1,278 +0,0 @@
-# Quick Start
-
-Get up and running with workspace-utils in minutes. This guide assumes you have a monorepo with workspaces already set up.
-
-## Prerequisites
-
-- A monorepo with Bun, pnpm, or npm workspaces
-- Node.js 18+ installed
-- workspace-utils installed as a dev dependency ([Installation Guide](./installation.md))
-
-## Setup Your Scripts
-
-First, add workspace-utils scripts to your root `package.json`:
-
-```json
-{
-	"scripts": {
-		"test": "wsu run test",
-		"build": "wsu build",
-		"dev": "wsu dev",
-		"lint": "wsu run lint"
-	}
-}
-```
-
-## Your First Command
-
-Navigate to your monorepo root and run:
-
-```bash
-npm run test
-```
-
-This will:
-
-1. 🔍 **Auto-detect** your package manager (Bun, pnpm, or npm)
-2. 📦 **Discover** all packages in your workspace
-3. ✅ **Filter** to packages that have a `test` script
-4. 🚀 **Run tests** in parallel across all packages
-5. 📊 **Display** a summary of results
-
-## Core Commands
-
-### Run Scripts Across Packages
-
-Add these 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 builds sequentially
-npm run lint           # Run linting with custom concurrency
-```
-
-### Build with Dependency Awareness
-
-Add build scripts:
-
-```json
-{
-	"scripts": {
-		"build": "wsu build",
-		"build:backend": "wsu build --filter '@myorg/backend-*'"
-	}
-}
-```
-
-Then run:
-
-```bash
-npm run build         # Build all packages in dependency order
-npm run build:backend # Build only backend packages
-```
-
-### Start Development Servers
-
-Add dev scripts:
-
-```json
-{
-	"scripts": {
-		"dev": "wsu dev",
-		"dev:apps": "wsu dev --filter 'apps/*'"
-	}
-}
-```
-
-Then run:
-
-```bash
-npm run dev      # Start all dev servers
-npm run dev:apps # Start only frontend packages
-```
-
-## Example Walkthrough
-
-Let's say you have this monorepo structure:
-
-```
-my-project/
-├── package.json
-├── packages/
-│   ├── utils/
-│   │   └── package.json (scripts: test, build, lint)
-│   └── ui-components/
-│       └── package.json (scripts: test, build, dev, storybook)
-└── apps/
-    └── web-app/
-        └── package.json (scripts: test, build, dev, start)
-```
-
-### Step 1: Run Tests
-
-```bash
-npm run test
-```
-
-**Output:**
-
-```
-🚀 Running script "test" across packages...
-
-📁 Workspace root: /Users/you/my-project
-📦 Found 3 packages
-
-✅ Running "test" in 3 packages:
-  • utils
-  • ui-components
-  • web-app
-
-🔧 Package manager: npm
-⚡ Execution mode: parallel (concurrency: 4)
-
-[utils] Starting: npm run test
-[ui-components] Starting: npm run test
-[web-app] Starting: npm run test
-[utils] ✅ Completed in 1,234ms
-[ui-components] ✅ Completed in 2,456ms
-[web-app] ✅ Completed in 3,789ms
-
-📊 Execution Summary:
-✅ Successful: 3
-⏱️  Total duration: 3,789ms
-```
-
-### Step 2: Build Everything
-
-```bash
-npm run build
-```
-
-**Output:**
-
-```
-🏗️  Building packages in dependency order...
-
-📊 Building dependency graph...
-✅ Build order determined: 2 batches
-
-📋 Build Plan:
-  Batch 1: utils
-  Batch 2: ui-components, web-app
-
-🔧 Package manager: npm
-⚡ Batch concurrency: 4
-
-🔄 Running batch 1/2 (1 packages)
-[utils] Starting: npm run build
-[utils] ✅ Completed in 2,000ms
-✅ Batch 1 completed successfully
-
-🔄 Running batch 2/2 (2 packages)
-[ui-components] Starting: npm run build
-[web-app] Starting: npm run build
-[ui-components] ✅ Completed in 3,000ms
-[web-app] ✅ Completed in 4,000ms
-✅ Batch 2 completed successfully
-
-🎉 All packages built successfully!
-```
-
-### Step 3: Start Development
-
-```bash
-npm run dev
-```
-
-**Output:**
-
-```
-🚀 Starting development servers with live log streaming...
-
-✅ Starting dev servers for 2 packages:
-  • ui-components
-  • web-app
-
-🔧 Package manager: npm
-⚡ Running 2 dev servers simultaneously
-
-🎬 Starting development servers...
-
-────────────────────────────────────────────────────────
-[ui-components] Starting: npm run dev
-[web-app] Starting: npm run dev
-[ui-components] Server running on http://localhost:6006
-[web-app] Server running on http://localhost:3000
-[ui-components] Hot reload enabled
-[web-app] Hot reload enabled
-...
-```
-
-## Filtering Examples
-
-Use filtering options in your package.json scripts:
-
-```json
-{
-	"scripts": {
-		"test:scope": "wsu run test --filter '@myorg/*'",
-		"build:apps": "wsu build --filter 'apps/*'",
-		"dev:frontend": "wsu dev --filter '*frontend*'",
-		"lint:utils": "wsu run lint --filter '*utils*'"
-	}
-}
-```
-
-Then run:
-
-```bash
-npm run test:scope     # Run tests only for scoped packages
-npm run build:apps     # Build only apps
-npm run dev:frontend   # Start dev servers for frontend packages
-npm run lint:utils     # Run linting for utility packages
-```
-
-## Common Patterns
-
-### Package.json Scripts
-
-Add these to your root `package.json` for convenient shortcuts:
-
-```json
-{
-	"scripts": {
-		"test": "wsu run test",
-		"test:sequential": "wsu run test --sequential",
-		"build": "wsu build",
-		"build:frontend": "wsu build --filter 'apps/*'",
-		"dev": "wsu dev",
-		"lint": "wsu run lint",
-		"lint:fix": "wsu run lint:fix"
-	}
-}
-```
-
-## What's Next?
-
-- 📚 Learn about [Configuration](./configuration.md) options
-- 🔧 Explore all [Commands](./commands/overview.md) in detail
-- 🎯 Check out [Common Patterns](./examples/common-patterns.md)
-- 🐛 See [Troubleshooting](./troubleshooting/common-issues.md) if you run into issues
-
-## Need Help?
-
-- View all available options: `npx wsu --help`
-- Get help for specific commands: `npx wsu run --help`
-- Check out the [CLI Reference](./reference/cli.md) for complete documentation