From c52c7e3c38cf37304dab4424d0efb5fa66e174aa Mon Sep 17 00:00:00 2001
From: Nicolas Gallagher <239676+necolas@users.noreply.github.com>
Date: Tue, 9 Jun 2026 18:42:40 -0700
Subject: [PATCH] tool(ws): Switch ws runner to <workspace>:<script> syntax

Change the workspace script runner from a space-separated
`bun ws <workspace> <script>` form to a single `<workspace>:<script>`
target token. The package part is everything before the first colon, so
script names that contain colons (e.g. `docs:trees:dev`) stay intact.

An empty package part fans out to every workspace, so `bun ws :test`
runs `test` in every workspace that defines it, equivalent to `'*:test'`.
Globs in the package part are still supported (`'packages/*:build'`).
Fan-out only runs the script where it exists, which is bun's existing
`-F` behavior; a single explicit workspace still errors on a missing
script. The old space-separated form now prints a helpful error pointing
at the new syntax.

Update all call sites and docs: root and CI scripts, app `build:deps`,
package READMEs, benchmark/profile usage strings, and the profile CLI
test assertion.
---
 .github/workflows/ci.yml                      | 14 ++--
 AGENTS.md                                     |  2 +-
 apps/demo/package.json                        |  2 +-
 apps/diffshub/package.json                    |  2 +-
 apps/docs/package.json                        |  2 +-
 package.json                                  |  2 +-
 ...benchmarkParseMergeConflictDiffFromFile.ts |  2 +-
 .../utils/parseMergeConflictDiffFromFile.ts   |  2 +-
 packages/path-store/README.md                 | 16 ++--
 packages/path-store/scripts/benchmark.ts      |  2 +-
 packages/path-store/scripts/profileDemo.ts    |  2 +-
 packages/trees/scripts/benchmark.ts           |  2 +-
 packages/trees/scripts/profileFileTree.ts     |  2 +-
 packages/trees/test/TESTING.md                |  4 +-
 .../trees/test/file-tree-profile-cli.test.ts  |  2 +-
 scripts/README.md                             | 34 +++++---
 scripts/ws.ts                                 | 82 +++++++++++++++----
 17 files changed, 115 insertions(+), 59 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a65dc429f..eac09e7d4 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -18,20 +18,20 @@ jobs:
         uses: ./.github/actions/setup
 
       - name: Build workspace packages
-        run: bun ws "packages/*" build
+        run: bun ws 'packages/*:build'
 
       # Build each docs site variant so both are build-verified. Every variant
       # writes to the same `.next/` dir (the per-site `distDir` in
       # next.config.mjs is dev-only), so these run sequentially.
       - name: Build docs (diffs, generates .source)
-        run: bun ws docs build
+        run: bun ws docs:build
 
       - name: Build docs (trees)
-        run: NEXT_PUBLIC_SITE=trees bun ws docs build
+        run: NEXT_PUBLIC_SITE=trees bun ws docs:build
 
       # diffshub is now its own standalone app rather than a docs site variant.
       - name: Build diffshub
-        run: bun ws diffshub build
+        run: bun ws diffshub:build
 
       - name: Upload build artifacts
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
@@ -108,7 +108,7 @@ jobs:
           name: build-output
 
       - name: Run unit tests (all packages)
-        run: bun ws "packages/*" test --sequential
+        run: bun ws 'packages/*:test' --sequential
 
       - name: Mount Playwright browsers
         uses: useblacksmith/stickydisk@13af8883542ca949a717e70fef89d15edbb29d88 # v1.2.0
@@ -119,7 +119,7 @@ jobs:
         run: bunx playwright@1.51.1 install --with-deps chromium
 
       - name: Run tests - trees e2e
-        run: bun ws trees test:e2e
+        run: bun ws trees:test:e2e
 
   typecheck:
     name: TypeScript
@@ -138,7 +138,7 @@ jobs:
           name: build-output
 
       - name: Type check all workspaces
-        run: bun run ws "*" tsc
+        run: bun run ws :tsc
 
   actions-pinned:
     name: Actions pinned to SHA
diff --git a/AGENTS.md b/AGENTS.md
index acb4378f3..efc190d06 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -18,7 +18,7 @@ export AGENT=1
   package intentionally needs its own range.
 - Run commands from the monorepo root when they operate across the repo. Use
   package directories for package-local scripts, or use
-  `bun ws <project> <task>` as the root shortcut when that fits the task.
+  `bun ws <project>:<task>` as the root shortcut when that fits the task.
 - Preserve trailing newlines at the end of files.
 
 ## Skills
diff --git a/apps/demo/package.json b/apps/demo/package.json
index 81b678a9a..d379154ec 100644
--- a/apps/demo/package.json
+++ b/apps/demo/package.json
@@ -5,7 +5,7 @@
   "type": "module",
   "scripts": {
     "build": "bun run build:deps && vite build",
-    "build:deps": "cd ../.. && bun ws \"packages/*\" build",
+    "build:deps": "cd ../.. && bun ws 'packages/*:build'",
     "build-types": "bun run build:deps && tsgo --build",
     "dev": "bun run build:deps && concurrently \"bun run dev:deps:diffs\" \"bun run dev:vite\" --names \"diffs,vite\" --prefix-colors \"blue,green\"",
     "dev:deps:diffs": "(cd ../../packages/diffs && bun run dev)",
diff --git a/apps/diffshub/package.json b/apps/diffshub/package.json
index 25f478bcd..c0868a2b4 100644
--- a/apps/diffshub/package.json
+++ b/apps/diffshub/package.json
@@ -5,7 +5,7 @@
   "scripts": {
     "build": "bun run build:deps && bun run build:next",
     "build:next": "next build",
-    "build:deps": "cd ../.. && bun ws \"packages/*\" build",
+    "build:deps": "cd ../.. && bun ws 'packages/*:build'",
     "dev": "export PORT=$((${PIERRE_PORT_OFFSET:-0} + 3692)) && bash ../../scripts/run-dev.sh \"$PORT\" -- bun run _dev",
     "prod": "export PORT=$((${PIERRE_PORT_OFFSET:-0} + 3692)) && bash ../../scripts/run-dev.sh \"$PORT\" -- bun run _prod",
     "_dev": "bun run build:deps && bun concurrently \"bun run dev:deps:diffs\" \"bun run dev:deps:tree\" \"bun run dev:deps:truncate\" \"bun run dev:next\" --names \"diffs,trees,truncate,diffshub\" --prefix-colors \"blue,green,yellow,purple\"",
diff --git a/apps/docs/package.json b/apps/docs/package.json
index 2b5c537f1..abdd632bb 100644
--- a/apps/docs/package.json
+++ b/apps/docs/package.json
@@ -5,7 +5,7 @@
   "scripts": {
     "build": "bun run build:deps && bun run generate-llms-txt && bun run build:next",
     "build:next": "next build",
-    "build:deps": "cd ../.. && bun ws \"packages/*\" build",
+    "build:deps": "cd ../.. && bun ws 'packages/*:build'",
     "diffs:dev": "export NEXT_PUBLIC_SITE=diffs PORT=$((${PIERRE_PORT_OFFSET:-0} + 3690)) && bash ../../scripts/run-dev.sh \"$PORT\" -- bun run _dev",
     "trees:dev": "export NEXT_PUBLIC_SITE=trees PORT=$((${PIERRE_PORT_OFFSET:-0} + 3691)) && bash ../../scripts/run-dev.sh \"$PORT\" -- bun run _dev",
     "_dev": "bun run build:deps && bun concurrently \"bun run dev:deps:diffs\" \"bun run dev:deps:tree\" \"bun run dev:deps:truncate\" \"bun run dev:next\" --names \"diffs,trees,truncate,docs\" --prefix-colors \"blue,green,yellow,purple\"",
diff --git a/package.json b/package.json
index a60f9738d..eb68c3c76 100644
--- a/package.json
+++ b/package.json
@@ -101,7 +101,7 @@
   "scripts": {
     "ws": "bun --silent scripts/ws.ts",
     "wt": "bun --silent scripts/wt.ts",
-    "tsc": "bun run ws \"*\" tsc",
+    "tsc": "bun ws :tsc",
     "clean": "bunx del-cli 'apps/*/.{next,source}' 'packages/*/dist' 'apps/*/tsconfig.tsbuildinfo' 'packages/*/tsconfig.tsbuildinfo'",
     "clean:all": "bun run clean && bunx del-cli '**/node_modules'",
     "icons:sprite": "node scripts/build-sprite.js && bun run format",
diff --git a/packages/diffs/scripts/benchmarkParseMergeConflictDiffFromFile.ts b/packages/diffs/scripts/benchmarkParseMergeConflictDiffFromFile.ts
index 15aa3aa22..a8ff4152b 100644
--- a/packages/diffs/scripts/benchmarkParseMergeConflictDiffFromFile.ts
+++ b/packages/diffs/scripts/benchmarkParseMergeConflictDiffFromFile.ts
@@ -95,7 +95,7 @@ function parseArgs(argv: string[]): BenchmarkConfig {
 
 function printHelpAndExit(): never {
   console.log(
-    'Usage: bun ws diffs benchmark:parse-merge-conflict -- [options]'
+    'Usage: bun ws diffs:benchmark:parse-merge-conflict -- [options]'
   );
   console.log('');
   console.log('Options:');
diff --git a/packages/diffs/src/utils/parseMergeConflictDiffFromFile.ts b/packages/diffs/src/utils/parseMergeConflictDiffFromFile.ts
index 2fa546ad3..f99a7c517 100644
--- a/packages/diffs/src/utils/parseMergeConflictDiffFromFile.ts
+++ b/packages/diffs/src/utils/parseMergeConflictDiffFromFile.ts
@@ -23,7 +23,7 @@
 //     bun test parseMergeConflictDiffFromFile
 //
 //   Performance benchmark (checksum must match 33121550):
-//     bun ws diffs benchmark:parse-merge-conflict
+//     bun ws diffs:benchmark:parse-merge-conflict
 //
 // If you encounter a bug:
 //   1. Add a new test case in test/parseMergeConflictDiffFromFile.test.ts with
diff --git a/packages/path-store/README.md b/packages/path-store/README.md
index 1e8ab5231..0aa75aab4 100644
--- a/packages/path-store/README.md
+++ b/packages/path-store/README.md
@@ -45,12 +45,12 @@ Private engine types stay in `internal-types.ts` or implementation files.
 Run these commands from the repository root:
 
 ```bash
-bun ws path-store test
-bun ws path-store tsc
-bun ws path-store benchmark -- --preset mutation
-bun ws path-store benchmark -- --preset cleanup
-bun ws path-store benchmark -- --preset static
-bun ws path-store benchmark:visible-tree-projection
-bun ws path-store profile:demo
-bun ws path-store profile:visible-tree-projection
+bun ws path-store:test
+bun ws path-store:tsc
+bun ws path-store:benchmark -- --preset mutation
+bun ws path-store:benchmark -- --preset cleanup
+bun ws path-store:benchmark -- --preset static
+bun ws path-store:benchmark:visible-tree-projection
+bun ws path-store:profile:demo
+bun ws path-store:profile:visible-tree-projection
 ```
diff --git a/packages/path-store/scripts/benchmark.ts b/packages/path-store/scripts/benchmark.ts
index 642780ce2..8f5f408a0 100644
--- a/packages/path-store/scripts/benchmark.ts
+++ b/packages/path-store/scripts/benchmark.ts
@@ -530,7 +530,7 @@ function parseArgs(argv: readonly string[]): BenchmarkCliOptions {
     }
 
     if (argument === '--help') {
-      console.log('Usage: bun ws path-store benchmark -- [options]');
+      console.log('Usage: bun ws path-store:benchmark -- [options]');
       console.log('');
       console.log('Options:');
       console.log(
diff --git a/packages/path-store/scripts/profileDemo.ts b/packages/path-store/scripts/profileDemo.ts
index ebb17d905..2fd6cc3ef 100644
--- a/packages/path-store/scripts/profileDemo.ts
+++ b/packages/path-store/scripts/profileDemo.ts
@@ -409,7 +409,7 @@ const AGGREGATE_METRIC_DEFINITIONS: Array<{
 ];
 
 function printHelpAndExit(): never {
-  console.log('Usage: bun ws path-store profile:demo -- [options]');
+  console.log('Usage: bun ws path-store:profile:demo -- [options]');
   console.log('');
   console.log(
     'Assumes Chrome is already running with --remote-debugging-port enabled.'
diff --git a/packages/trees/scripts/benchmark.ts b/packages/trees/scripts/benchmark.ts
index cbb1ee012..c33cc59bd 100644
--- a/packages/trees/scripts/benchmark.ts
+++ b/packages/trees/scripts/benchmark.ts
@@ -181,7 +181,7 @@ function parseArgs(argv: readonly string[]): BenchmarkCliOptions {
     }
 
     if (argument === '--help') {
-      console.log('Usage: bun ws trees benchmark -- [options]');
+      console.log('Usage: bun ws trees:benchmark -- [options]');
       console.log('');
       console.log('Options:');
       console.log(
diff --git a/packages/trees/scripts/profileFileTree.ts b/packages/trees/scripts/profileFileTree.ts
index 0bce2d73c..df4fd4111 100644
--- a/packages/trees/scripts/profileFileTree.ts
+++ b/packages/trees/scripts/profileFileTree.ts
@@ -494,7 +494,7 @@ const AGGREGATE_METRIC_DEFINITIONS: Array<{
 const INTEGER_FORMATTER = new Intl.NumberFormat('en-US');
 
 function printHelpAndExit(): never {
-  console.log('Usage: bun ws trees profile:file-tree -- [options]');
+  console.log('Usage: bun ws trees:profile:file-tree -- [options]');
   console.log('');
   console.log(
     'Assumes Chrome is already running with --remote-debugging-port enabled.'
diff --git a/packages/trees/test/TESTING.md b/packages/trees/test/TESTING.md
index 3ea5f594c..d321cda8a 100644
--- a/packages/trees/test/TESTING.md
+++ b/packages/trees/test/TESTING.md
@@ -34,8 +34,8 @@ If a unit test can prove behavior, write a unit test instead.
 From repo root:
 
 ```bash
-bun ws trees test
-bun ws trees test:e2e
+bun ws trees:test
+bun ws trees:test:e2e
 ```
 
 `test:e2e` automatically:
diff --git a/packages/trees/test/file-tree-profile-cli.test.ts b/packages/trees/test/file-tree-profile-cli.test.ts
index d96f9a101..d29cc3d33 100644
--- a/packages/trees/test/file-tree-profile-cli.test.ts
+++ b/packages/trees/test/file-tree-profile-cli.test.ts
@@ -29,7 +29,7 @@ test('profile:file-tree CLI help advertises the expected workload/render workflo
 
   expect(result.exitCode).toBe(0);
   expect(stderr).toBe('');
-  expect(stdout).toContain('bun ws trees profile:file-tree');
+  expect(stdout).toContain('bun ws trees:profile:file-tree');
   expect(stdout).toContain('linux-5x');
   expect(stdout).toContain('file-tree-profile.html');
   expect(stdout).toContain('starts `bun run chrome` automatically');
diff --git a/scripts/README.md b/scripts/README.md
index 00383cf53..25d3425d6 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -22,7 +22,7 @@ most common workflows.
 
 ## `bun ws` — the workspace script runner
 
-`bun ws <package> <script> [args…]` runs an npm script inside a specific
+`bun ws <package>:<script> [args…]` runs an npm script inside a specific
 workspace. It exists for three reasons:
 
 1. You can run it from anywhere in the monorepo — you don't have to `cd` into
@@ -35,16 +35,24 @@ workspace. It exists for three reasons:
 ### Syntax
 
 ```bash
-bun ws <package> <script> [args...]
-bun ws <package> <script> --verbose        # don't elide lines in output
-bun ws 'packages/*' <script>                # fan out across a glob
-bun ws '*' <script>                         # every workspace (apps + packages)
+bun ws <package>:<script> [args...]
+bun ws <package>:<script> --verbose         # don't elide lines in output
+bun ws 'packages/*:<script>'                # fan out across a glob
+bun ws ':<script>'                          # every workspace that defines it
 ```
 
-`ws` forwards every argument after the script name to the underlying `bun run`
+The target is a single `<package>:<script>` token. The package part comes before
+the first colon; everything after it is the script name (so script names that
+contain colons, like `trees:dev` → `docs:trees:dev`, stay intact). An empty
+package part (`:test`) fans out to every workspace, equivalent to `'*:test'`.
+
+`ws` forwards every argument after the target to the underlying `bun run`
 invocation. You do **not** need `--` to separate them unless a downstream tool
 requires it. The only flag `ws` itself eats is `-v` / `--verbose`.
 
+When fanning out across a glob or the empty package part, `ws` runs the script
+only in the workspaces that actually define it and silently skips the rest.
+
 ### Package name resolution
 
 In priority order:
@@ -57,11 +65,11 @@ In priority order:
 ### Examples
 
 ```bash
-bun ws diffs build           # build packages/diffs
-bun ws docs trees:dev        # run the docs trees dev server
-bun ws trees test            # bun test in packages/trees
-bun ws 'packages/*' build    # build every package
-bun ws '*' tsc               # typecheck everything
+bun ws diffs:build           # build packages/diffs
+bun ws docs:trees:dev        # run the docs trees dev server
+bun ws trees:test            # bun test in packages/trees
+bun ws 'packages/*:build'    # build every package
+bun ws :tsc                  # typecheck everything
 ```
 
 ### How `ws` interacts with worktrees
@@ -271,7 +279,7 @@ no central registry file.
    PIERRE_WORKTREE_SLUG=drag-drop-fix
    PIERRE_PORT_OFFSET=30
    ```
-2. When you run `bun ws docs trees:dev`, `ws` walks up from your cwd, finds
+2. When you run `bun ws docs:trees:dev`, `ws` walks up from your cwd, finds
    `.env.worktree`, and injects its keys into the child env.
 3. The package.json script itself uses shell arithmetic to derive the final
    port:
@@ -326,7 +334,7 @@ permissions dialog hadn't finished resolving yet.
 ```bash
 bun run wt new drag-drop-fix
 cd ~/pierre/pierre-worktrees/drag-drop-fix
-bun ws docs trees:dev
+bun ws docs:trees:dev
 # → serves on http://localhost:<3691 + offset>, tab title prefixed with
 #   an emoji + "[drag-drop-fix]"
 ```
diff --git a/scripts/ws.ts b/scripts/ws.ts
index 9d319efb4..b9bc28e3f 100644
--- a/scripts/ws.ts
+++ b/scripts/ws.ts
@@ -313,15 +313,26 @@ if (runModeFlag) {
   args.splice(args.indexOf(runModeFlag), 1);
 }
 
-const [pkgArg, ...scriptArgs] = args;
+// The first positional argument is the `<workspace>:<script>` target; every
+// argument after it is forwarded verbatim to the underlying script.
+const [target, ...scriptArgs] = args;
 
-if (!pkgArg || scriptArgs.length === 0) {
-  console.log('Usage: bun ws <package> <script> [args...] [--verbose]');
+function printUsage() {
+  console.log('Usage: bun ws <workspace>:<script> [args...] [--verbose]');
   console.log('');
-  console.log('Filters:');
+  console.log('Target:');
+  console.log('  <workspace>:<script>  Run <script> in one workspace');
+  console.log(
+    '  :<script>             Run <script> in every workspace that defines it'
+  );
+  console.log('');
+  console.log('Workspace part:');
   console.log('  <name>           Matches @pierre/<name> in package.json');
   console.log('  packages/<name>  Matches directory on filesystem');
   console.log('  apps/<name>      Matches directory on filesystem');
+  console.log('  packages/*       Every package (glob)');
+  console.log('  apps/*           Every app (glob)');
+  console.log('  *  (or empty)    Every workspace');
   console.log('');
   console.log('Options:');
   console.log('  -v, --verbose    Show full output (no line elision)');
@@ -333,16 +344,52 @@ if (!pkgArg || scriptArgs.length === 0) {
   );
   console.log('');
   console.log('Examples:');
-  console.log('  bun ws diffs build');
-  console.log('  bun ws diffs test');
-  console.log('  bun ws diffs test --verbose    # full output');
-  console.log('  bun ws packages/diffs build    # path-based');
-  console.log("  bun ws 'packages/*' test       # all packages");
-  console.log("  bun ws 'apps/*' dev            # all apps");
-  console.log("  bun ws '*' build               # all workspaces");
+  console.log('  bun ws diffs:build');
+  console.log('  bun ws diffs:test');
+  console.log('  bun ws diffs:test --verbose       # full output');
+  console.log('  bun ws packages/diffs:build       # path-based');
+  console.log("  bun ws 'packages/*:test'          # all packages");
+  console.log("  bun ws 'apps/*:dev'               # all apps");
+  console.log(
+    '  bun ws :test                      # every workspace with test'
+  );
+  console.log(
+    "  bun ws '*:build'                  # every workspace (explicit)"
+  );
+}
+
+if (!target) {
+  printUsage();
   process.exit(0);
 }
 
+// Targets are `<workspace>:<script>`. Splitting on the first colon keeps script
+// names that themselves contain colons intact (e.g. `docs:trees:dev`,
+// `:test:e2e`). An empty workspace part (`:test`) fans out to every workspace.
+const colonIndex = target.indexOf(':');
+if (colonIndex === -1) {
+  console.error(
+    `Invalid target "${target}". The ws syntax is now <workspace>:<script>.`
+  );
+  const suggestedScript = scriptArgs.find((arg) => !arg.startsWith('-'));
+  if (suggestedScript) {
+    console.error(`Did you mean: bun ws ${target}:${suggestedScript}`);
+  } else {
+    console.error(`For example: bun ws ${target}:build`);
+  }
+  process.exit(1);
+}
+
+const pkgArg = target.slice(0, colonIndex);
+const scriptName = target.slice(colonIndex + 1);
+
+if (!scriptName) {
+  console.error(
+    `Missing script name in "${target}". Expected <workspace>:<script>.`
+  );
+  process.exit(1);
+}
+
 // Resolve package directory for direct execution
 function resolvePackageDir(pkg: string): string | null {
   // Check if it's already a path
@@ -358,11 +405,13 @@ function resolvePackageDir(pkg: string): string | null {
   return null;
 }
 
-// Glob patterns (e.g. '*', 'packages/*') must use bun run -F
-if (pkgArg.includes('*')) {
+// An empty workspace part (`:test`) or a glob (`*`, `packages/*`) fans out via
+// `bun run -F`, which already runs the script only in the workspaces that
+// define it and silently skips the rest.
+if (pkgArg === '' || pkgArg.includes('*')) {
   const isPath = pkgArg.startsWith('packages/') || pkgArg.startsWith('apps/');
   let filter: string;
-  if (pkgArg === '*') {
+  if (pkgArg === '' || pkgArg === '*') {
     filter = '*';
   } else if (isPath) {
     filter = `./${pkgArg}`;
@@ -376,7 +425,7 @@ if (pkgArg.includes('*')) {
 
   const proc = spawn(
     'bun',
-    ['run', '-F', filter, ...outputFlags, ...scriptArgs],
+    ['run', '-F', filter, ...outputFlags, scriptName, ...scriptArgs],
     {
       stdio: 'inherit',
       cwd,
@@ -394,7 +443,6 @@ if (pkgArg.includes('*')) {
 
   const pkgJsonPath = resolve(pkgDir, 'package.json');
   const pkgJson = JSON.parse(await Bun.file(pkgJsonPath).text());
-  const scriptName = scriptArgs[0];
   const scriptCmd = pkgJson.scripts?.[scriptName];
 
   if (!scriptCmd) {
@@ -402,7 +450,7 @@ if (pkgArg.includes('*')) {
     process.exit(1);
   }
 
-  const restArgs = scriptArgs.slice(1); // args after script name (e.g., -- --update-snapshots)
+  const restArgs = scriptArgs; // forwarded args (e.g., -- --update-snapshots)
 
   // If the script contains shell operators, run via shell
   const needsShell = /&&|\|\||[|;]/.test(scriptCmd);