workspace-utils 1.0.0 → 1.0.1

package/dist/package.json

@@ -0,0 +1,57 @@
+{
+	"name": "workspace-utils",
+	"version": "1.0.1",
+	"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",
+	"files": [
+		"dist/"
+	],
+	"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"
+	}
+}

package/package.json

@@ -1,9 +1,12 @@
 {
 	"name": "workspace-utils",
-	"version": "1.0.0",
+	"version": "1.0.1",
 	"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",
+	"files": [
+		"dist/"
+	],
 	"bin": {
 		"workspace-utils": "./dist/index.js",
 		"wsu": "./dist/index.js"

package/.github/workflows/mdbook.yml

@@ -1,64 +0,0 @@
-# Sample workflow for building and deploying a mdBook site to GitHub Pages
-#
-# To get started with mdBook see: https://rust-lang.github.io/mdBook/index.html
-#
-name: Deploy mdBook site to Pages
-
-defaults:
-  run:
-    working-directory: docs
-
-on:
-  # Runs on pushes targeting the default branch
-  push:
-    branches: ['main']
-
-  # Allows you to run this workflow manually from the Actions tab
-  workflow_dispatch:
-
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
-# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
-concurrency:
-  group: 'pages'
-  cancel-in-progress: false
-
-jobs:
-  # Build job
-  build:
-    runs-on: ubuntu-latest
-    env:
-      MDBOOK_VERSION: 0.4.52
-    steps:
-      - uses: actions/checkout@v4
-      - name: Install mdBook
-        run: |
-          curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh
-          rustup update
-          cargo install --version ${MDBOOK_VERSION} mdbook
-      - name: Setup Pages
-        id: pages
-        uses: actions/configure-pages@v5
-      - name: Build with mdBook
-        run: mdbook build
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: ./docs/book
-
-  # Deployment job
-  deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    needs: build
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4

package/.prettierignore

@@ -1,22 +0,0 @@
-# Dependencies
-node_modules/
-dist/
-
-# Build outputs
-*.js
-*.d.ts
-
-# Lock files
-pnpm-lock.yaml
-yarn.lock
-package-lock.json
-
-# Test workspaces and temporary test directories
-tests/
-test-temp*/
-
-# Documentation
-CHANGELOG.md
-
-# Git
-.git/

package/.prettierrc

@@ -1,13 +0,0 @@
-{
-	"useTabs": true,
-	"tabWidth": 2,
-	"semi": true,
-	"singleQuote": true,
-	"quoteProps": "as-needed",
-	"trailingComma": "es5",
-	"bracketSpacing": true,
-	"bracketSameLine": false,
-	"arrowParens": "avoid",
-	"printWidth": 100,
-	"endOfLine": "lf"
-}

package/docs/book.toml

@@ -1,10 +0,0 @@
-[book]
-authors = ["Torsten Dittmann"]
-language = "en"
-src = "src"
-title = "workspace-utils"
-description = "A CLI tool to orchestrate scripts across monorepo workspaces with parallel execution and dependency-aware builds"
-
-[output.html]
-git-repository-url = "https://github.com/torstendittmann/workspace-utils"
-edit-url-template = "https://github.com/torstendittmann/workspace-utils/edit/main/docs/{path}"

package/docs/src/SUMMARY.md

@@ -1,24 +0,0 @@
-# Summary
-
-[Introduction](./introduction.md)
-
-# Getting Started
-
-- [Installation](./installation.md)
-- [Quick Start](./quick-start.md)
-- [Configuration](./configuration.md)
-
-# Commands
-
-- [Overview](./commands/overview.md)
-- [run](./commands/run.md)
-- [build](./commands/build.md)
-- [dev](./commands/dev.md)
-
-# Usage Examples
-
-- [Examples](./examples.md)
-
-# Help
-
-- [Troubleshooting](./troubleshooting.md)

package/docs/src/commands/build.md

@@ -1,110 +0,0 @@
-# build Command
-
-The `build` command builds packages in dependency order, ensuring that dependencies are built before their dependents.
-
-## Recommended Usage
-
-Add to your `package.json` scripts:
-
-```json
-{
-	"scripts": {
-		"build": "wsu build",
-		"build:apps": "wsu build --filter 'apps/*'",
-		"build:slow": "wsu build --concurrency 2"
-	}
-}
-```
-
-Then run:
-
-```bash
-npm run build      # Build all packages in dependency order
-npm run build:apps # Build only apps
-npm run build:slow # Build with limited concurrency
-```
-
-## Direct Usage (if needed)
-
-```bash
-wsu build [options]
-```
-
-## How it Works
-
-1. **Analyzes dependencies** - Reads `package.json` files to understand package relationships
-2. **Creates build batches** - Groups packages that can be built in parallel
-3. **Executes in order** - Runs builds batch by batch, respecting dependencies
-
-## Options
-
-| Option                   | Description                     | Default      |
-| ------------------------ | ------------------------------- | ------------ |
-| `--filter <pattern>`     | Filter packages by glob pattern | All packages |
-| `--concurrency <number>` | Max concurrent builds per batch | `4`          |
-
-## Examples
-
-### Basic Usage
-
-Add scripts to your `package.json`:
-
-```json
-{
-	"scripts": {
-		"build": "wsu build",
-		"build:apps": "wsu build --filter 'apps/*'",
-		"build:limited": "wsu build --concurrency 2"
-	}
-}
-```
-
-Then run:
-
-```bash
-npm run build         # Build all packages in dependency order
-npm run build:apps    # Build only apps
-npm run build:limited # Build with limited concurrency
-```
-
-### Example Output
-
-```
-🏗️  Building packages in dependency order...
-
-📊 Building dependency graph...
-✅ Build order determined: 3 batches
-
-📋 Build Plan:
-  Batch 1: @company/utils
-  Batch 2: @company/ui-components, @company/api-client
-  Batch 3: apps/web-app
-
-🔧 Package manager: pnpm
-⚡ Batch concurrency: 4
-
-🔄 Running batch 1/3 (1 packages)
-[@company/utils] ✅ Completed in 2,000ms
-
-🔄 Running batch 2/3 (2 packages)
-[@company/ui-components] ✅ Completed in 3,000ms
-[@company/api-client] ✅ Completed in 2,500ms
-
-🔄 Running batch 3/3 (1 packages)
-[apps/web-app] ✅ Completed in 4,000ms
-
-🎉 All packages built successfully!
-```
-
-## When to Use
-
-- **Production builds** - When dependency order matters
-- **CI/CD pipelines** - Reliable, predictable builds
-- **Publishing** - Ensure dependencies are built first
-- **Clean builds** - Start from scratch with proper ordering
-
-## Error Handling
-
-- If a package fails, the current batch stops
-- Subsequent batches are skipped
-- Exit code is non-zero if any builds fail

package/docs/src/commands/dev.md

@@ -1,118 +0,0 @@
-# dev Command
-
-The `dev` command starts development servers across multiple packages with live log streaming and graceful shutdown.
-
-## Recommended Usage
-
-Add to your `package.json` scripts:
-
-```json
-{
-	"scripts": {
-		"dev": "wsu dev",
-		"dev:apps": "wsu dev --filter 'apps/*'",
-		"dev:limited": "wsu dev --concurrency 2"
-	}
-}
-```
-
-Then run:
-
-```bash
-npm run dev         # Start all dev servers
-npm run dev:apps    # Start only frontend packages
-npm run dev:limited # Limit concurrent servers
-```
-
-## Direct Usage (if needed)
-
-```bash
-wsu dev [options]
-```
-
-## How it Works
-
-1. **Finds packages** with `dev` scripts
-2. **Starts servers** in parallel with live log streaming
-3. **Color-codes output** for easy identification
-4. **Handles shutdown** gracefully when you press Ctrl+C
-
-## Options
-
-| Option                   | Description                     | Default      |
-| ------------------------ | ------------------------------- | ------------ |
-| `--filter <pattern>`     | Filter packages by glob pattern | All packages |
-| `--concurrency <number>` | Max concurrent dev servers      | `4`          |
-
-## Examples
-
-### Basic Usage
-
-Add scripts to your `package.json`:
-
-```json
-{
-	"scripts": {
-		"dev": "wsu dev",
-		"dev:frontend": "wsu dev --filter 'apps/*'",
-		"dev:limited": "wsu dev --concurrency 2"
-	}
-}
-```
-
-Then run:
-
-```bash
-npm run dev          # Start all dev servers
-npm run dev:frontend # Start only frontend packages
-npm run dev:limited  # Limit concurrent servers
-```
-
-### Example Output
-
-```
-🚀 Starting development servers with live log streaming...
-
-✅ Starting dev servers for 3 packages:
-  • @company/ui-components
-  • apps/web-app
-  • apps/mobile-app
-
-🔧 Package manager: npm
-⚡ Running 3 dev servers simultaneously
-💡 Tip: Use Ctrl+C to stop all development servers
-
-🎬 Starting development servers...
-
-────────────────────────────────────────────────────────
-[@company/ui-components] Starting: npm run dev
-[apps/web-app] Starting: npm run dev
-[apps/mobile-app] Starting: npm run dev
-[@company/ui-components] Server running on http://localhost:6006
-[apps/web-app] Server running on http://localhost:3000
-[apps/mobile-app] Expo running on http://localhost:19000
-[@company/ui-components] Hot reload enabled
-[apps/web-app] Hot reload enabled
-...
-```
-
-## Features
-
-- **Live log streaming** - See real-time output from all servers
-- **Color-coded prefixes** - Each package has its own color
-- **Graceful shutdown** - Ctrl+C stops all servers cleanly
-- **No timestamps** - Clean output focused on development
-
-## When to Use
-
-- **Local development** - Start all services at once
-- **Full-stack development** - Frontend, backend, and services together
-- **Debugging** - See logs from multiple packages simultaneously
-- **Team development** - Consistent development environment
-
-## Tips
-
-- Use filtering to start only the packages you're working on
-- Keep concurrency reasonable to avoid overwhelming your system
-- Each package gets a unique color for easy log identification
-- Press Ctrl+C once to gracefully stop all servers

package/docs/src/commands/overview.md

@@ -1,239 +0,0 @@
-# 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