workspace-utils 1.0.0

package/.github/workflows/mdbook.yml

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

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

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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 pnpmono
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,278 @@
+# 📦 bunmono
+
+A **Bun-powered CLI tool** for orchestrating scripts across **Bun workspaces** with parallel execution, dependency-aware builds, and real-time log streaming.
+
+## ✨ Features
+
+- 🚀 **Parallel script execution** across multiple packages
+- 📊 **Dependency-aware builds** with topological sorting
+- 🎨 **Color-coded, prefixed logs** for easy identification
+- 🔍 **Package filtering** with glob patterns
+- ⚡ **Configurable concurrency** limits
+- 🏗️ **Smart build ordering** respecting package dependencies
+- 📺 **Real-time log streaming** with timestamps
+- 🎯 **Zero configuration** - works with any Bun workspace
+- 🟡 **Bun native** - designed specifically for Bun workspaces
+
+## 🛠️ Installation
+
+```bash
+# Install globally
+bun install -g bunmono
+
+# Or use with bunx
+bunx bunmono
+```
+
+## 🚀 Quick Start
+
+```bash
+# Run tests across all packages (parallel by default)
+bunmono run test
+
+# Build packages in dependency order
+bunmono build
+
+# Start all dev servers with live logs
+bunmono dev
+
+# Run linting on specific packages
+bunmono run lint --filter "@myorg/*"
+```
+
+## 📖 Commands
+
+### `run <script>`
+
+Run a script across multiple packages with support for parallel or sequential execution.
+
+```bash
+bunmono run <script> [options]
+```
+
+**Options:**
+
+- `-c, --concurrency <number>` - Maximum concurrent processes (default: 4)
+- `-f, --filter <pattern>` - Filter packages by glob pattern
+- `--sequential` - Run scripts sequentially (default is parallel)
+
+**Examples:**
+
+```bash
+# Run tests across all packages (parallel by default)
+bunmono run test
+
+# Run build sequentially
+bunmono run build --sequential
+
+# Run dev only for frontend packages (parallel by default)
+bunmono run dev --filter "@myorg/frontend-*"
+
+# Run with custom concurrency
+bunmono run lint --concurrency 8
+```
+
+### `build`
+
+Build packages in dependency order, ensuring dependencies are built before dependents.
+
+```bash
+bunmono build [options]
+```
+
+**Options:**
+
+- `-f, --filter <pattern>` - Filter packages by pattern
+- `-c, --concurrency <number>` - Max concurrent builds per batch (default: 4)
+- `--skip-unchanged` - Skip unchanged packages (future feature)
+
+**Examples:**
+
+```bash
+# Build all packages in dependency order
+bunmono build
+
+# Build only specific scope
+bunmono build --filter "@myorg/backend-*"
+
+# Build with higher concurrency per batch
+bunmono build --concurrency 8
+```
+
+### `dev`
+
+Start development servers with live log streaming and graceful shutdown.
+
+```bash
+bunmono dev [options]
+```
+
+**Options:**
+
+- `-f, --filter <pattern>` - Filter packages by pattern
+- `-c, --concurrency <number>` - Max concurrent dev servers (default: 4)
+
+**Examples:**
+
+```bash
+# Start all dev servers
+bunmono dev
+
+# Start only frontend dev servers
+bunmono dev --filter "apps/*"
+
+# Limit concurrent dev servers
+bunmono dev --concurrency 2
+```
+
+## 🔍 Package Filtering
+
+Use glob patterns to target specific packages:
+
+```bash
+# Scope-based filtering (runs in parallel by default)
+bunmono run test --filter "@myorg/*"
+bunmono run build --filter "@myorg/backend-*"
+
+# Path-based filtering
+bunmono run dev --filter "apps/*"
+bunmono run lint --filter "packages/*"
+
+# Name-based filtering with sequential execution
+bunmono run test --filter "*-utils" --sequential
+bunmono run build --filter "*frontend*"
+```
+
+## 📊 Dependency Management
+
+The tool automatically:
+
+1. **Parses your workspace** from `package.json` workspaces
+2. **Builds a dependency graph** from `package.json` files
+3. **Calculates build order** using topological sorting
+4. **Detects circular dependencies** and reports them
+5. **Executes in batches** where each batch can run in parallel
+
+### Example Dependency Resolution
+
+Given this structure:
+
+```
+├── packages/
+│   ├── shared-utils/     (no dependencies)
+│   ├── ui-components/    (depends on shared-utils)
+│   └── api-client/       (depends on shared-utils)
+└── apps/
+    └── web-app/          (depends on ui-components, api-client)
+```
+
+Build order will be:
+
+1. **Batch 1:** `shared-utils` (parallel with others in batch)
+2. **Batch 2:** `ui-components`, `api-client` (parallel with each other)
+3. **Batch 3:** `web-app`
+
+## 🎨 Log Output
+
+Logs are color-coded and prefixed for easy identification:
+
+```
+[shared-utils] Building shared utilities with Bun...
+[ui-components] Starting component library build...
+[web-app] Compiling application...
+[shared-utils] ✅ Completed in 1,234ms
+[ui-components] ✅ Completed in 2,456ms
+[web-app] ✅ Completed in 3,789ms
+```
+
+## 📁 Workspace Requirements
+
+Your project must have a `package.json` with `workspaces` field at the root.
+
+### Example workspace `package.json`:
+
+```json
+{
+	"name": "my-monorepo",
+	"private": true,
+	"workspaces": ["packages/*", "apps/*"],
+	"scripts": {
+		"build": "bunmono build",
+		"dev": "bunmono dev",
+		"test": "bunmono run test"
+	}
+}
+```
+
+## 🟡 Why Bun?
+
+This tool is specifically designed for **Bun workspaces** because:
+
+- **Native performance** - Built with Bun for maximum speed
+- **Simple workspace config** - Uses standard `package.json` workspaces
+- **Modern tooling** - Leverages Bun's fast package manager and runtime
+- **Developer experience** - Seamless integration with Bun's ecosystem
+
+## ⚡ Performance Tips
+
+1. **Use filtering** to target only the packages you need
+2. **Adjust concurrency** based on your system resources (default: 4)
+3. **Parallel by default** - most scripts benefit from parallel execution
+4. **Use --sequential** only when order matters or for resource-intensive tasks
+5. **For builds**, dependency ordering ensures correct execution even in parallel batches
+6. **For dev servers**, use reasonable concurrency limits to avoid resource exhaustion
+
+## 🐛 Troubleshooting
+
+### "No workspaces configuration found"
+
+Ensure your root `package.json` has a `workspaces` field with package patterns.
+
+### "Circular dependencies detected"
+
+Check your package dependencies for circular references:
+
+```bash
+# This will show the circular dependency chain
+bunmono build
+```
+
+### "No packages found with script"
+
+Verify your packages have the required script in their `package.json`:
+
+```bash
+# Check which packages have the script
+bunmono run nonexistent-script
+```
+
+## 🛣️ Roadmap
+
+- [ ] **Caching** - Skip builds for unchanged packages
+- [ ] **Watch mode** - Restart processes on file changes
+- [ ] **Interactive mode** - Focus on specific package logs
+- [ ] **Custom log formatters** - Configurable output styles
+- [ ] **Dry run mode** - Preview execution plan
+- [ ] **Bun-specific optimizations** - Leverage Bun features for better performance
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/amazing-feature`
+3. Commit your changes: `git commit -m 'Add amazing feature'`
+4. Push to the branch: `git push origin feature/amazing-feature`
+5. Open a Pull Request
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- Built with [Bun](https://bun.sh) for blazing fast performance
+- Inspired by the need for better Bun workspace tooling
+- Thanks to the Bun team for creating an excellent runtime and package manager
+
+---
+
+**Made with ❤️ for the Bun community**

package/docs/book.toml

@@ -0,0 +1,10 @@
+[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

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

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

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