bun-workspaces 1.9.0 → 1.10.0

package/AGENTS.md

@@ -0,0 +1,537 @@
+<!-- bun-workspaces (npm package) agent documentation begin -->
+## Project Overview
+
+bun-workspaces is a CLI and TypeScript API to help manage Bun monorepos. It reads `bun.lock` to find all workspaces in the project. It is referred to as "bw" for short, which is also the recommended CLI alias. The overall goal is a monorepo tool that is more lightweight than others, with still powerful comparable features, requiring no special config to get started, only a standard Bun repo using workspaces.
+
+Three main domain terms to know:
+
+- Project: generally represents a monorepo and is defined by the root `package.json` file
+- Workspace: a nested package within a project. The root package.json can count as a workspace as well, but by default, only nested packages are considered workspaces.
+- Script: an entry in the `scripts` field of a workspace's `package.json` file. bw can also run one-off commands known as "inline scripts," which can use the Bun shell or system shell (`sh -c` or `cmd /d /s /c` for windows).
+
+bw also supports **affected workspace** detection: given a set of changed files (from a git diff or an explicit list), it determines which workspaces are meaningfully changed. This drives `bw list-affected`/`bw run-affected` for orchestrating builds, tests, etc. across only the workspaces that need them.
+
+## Concepts
+
+### Workspace patterns
+
+Many features accept a list of workspace patterns to match a subset of workspaces:
+
+`[not:][(name|alias|path|tag):][re:]<value>`
+
+By default, a pattern matches the workspace name or alias: `my-workspace-name` or `my-alias-name`. Aliases are defined in config explained below.
+
+Patterns can include a wildcard to match only by workspace name: `my-workspace-*`.
+
+- Alias pattern specifier: `alias:my-alias-*`.
+- Path pattern specifier (supports glob): `path:packages/**/*`.
+- Name pattern specifier: `name:my-workspace-*`.
+- Tag pattern specifier: `tag:my-tag`.
+- Any pattern can start with `not:` to negate the pattern. (e.g. "not:my-workspace-name", "not:tag:my-tag-\*") This excludes workspaces that match any other present patterns from a result.
+- Regex pattern modifier can be applied before the pattern value: `re:` (e.g. "re:^my-workspace-.+" or "not:alias:re:^my-alias-.+")
+
+#### Special selectors
+
+- Special root workspace selector: `@root`. This is a reference to the root workspace, whether it's included in a Project's workspace list or not.
+
+### Workspace Script Metadata
+
+Scripts ran via bun-workspaces can access metadata about the workspace, script, and project
+via env vars. This same metadata can also be interpolated into inline scripts and appended args.
+
+```typescript
+// in a workspace's script invoked by bun-workspaces using a metadata function
+import { getWorkspaceScriptMetadata } from "bun-workspaces/script";
+
+// Use the helper within a script that was invoked via bun-workspaces
+const projectPath = getWorkspaceScriptMetadata("projectPath");
+const projectName = getWorkspaceScriptMetadata("projectName");
+const workspaceName = getWorkspaceScriptMetadata("workspaceName");
+const workspacePath = getWorkspaceScriptMetadata("workspacePath");
+const workspaceRelativePath = getWorkspaceScriptMetadata(
+  "workspaceRelativePath",
+);
+const scriptName = getWorkspaceScriptMetadata("scriptName");
+```
+
+```typescript
+// In a script, but accessing the same data via plain environment variables (same values as previous example)
+const projectPath = process.env.BW_PROJECT_PATH;
+const workspaceName = process.env.BW_WORKSPACE_NAME;
+const workspacePath = process.env.BW_WORKSPACE_PATH;
+const workspaceRelativePath = process.env.BW_WORKSPACE_RELATIVE_PATH;
+const scriptName = process.env.BW_SCRIPT_NAME;
+```
+
+```bash
+# interpolated
+bw run "bun <projectPath>/my-script.ts" --inline \
+  --inline-name="my-script-name" \
+  --args="<workspaceName> <workspacePath>"
+```
+
+### Affected workspaces
+
+A workspace is "affected" when something in its set of **inputs** has changed. Inputs default to:
+
+- Files in the workspace's directory (only git-trackable files; the default file pattern is `"."`)
+- Workspace dependencies — if a workspace dep is affected for any reason, dependents cascade as affected
+- All non-workspace dependencies declared in its `package.json` (across all four maps: `dependencies`, `devDependencies`, `peerDependencies`, `optionalDependencies`). Version changes are detected by diffing resolved versions in `bun.lock`. For `peerDependencies`/`optionalDependencies`, lockfile presence is the gate — an unresolved optional (e.g., a platform-skipped native binding) emits no change.
+
+Inputs are configurable per workspace (`defaultInputs`) and per script (`scripts[name].inputs`):
+
+- `files`: file/dir/glob patterns relative to the workspace. Leading `/` makes a pattern relative to the project root. Prefix `!` to exclude. Only git-trackable files match.
+- `workspacePatterns`: workspace patterns whose matched workspaces are treated as inputs (like dependencies, but without needing a real `package.json` dep).
+- `externalDependencies`: an allowlist of package names. Omitted = all external deps participate; `[]` = none participate; non-empty = only listed names participate (intersected with the workspace's actual external deps).
+
+There are two diff sources:
+
+- **git** (default): diff `HEAD` against the configured base ref (default `main`, configurable via `affectedBaseRef` in the root config or `BW_AFFECTED_BASE_REF_DEFAULT` env var). Uncommitted changes (staged, unstaged, untracked) are included by default. Gitignored files never participate.
+- **fileList**: pass changed files explicitly (paths, dirs, or globs) — bypasses git entirely.
+
+Use `--explain` for a per-workspace summary of changed inputs and dep cascade reasons, and `--explain --detailed` for full per-file/edge breakdowns including the affected-dep chain.
+
+### CLI examples:
+
+```bash
+alias bw="bunx bun-workspaces"
+
+bw list-workspaces # human-readable output
+bw ls --json --pretty # ls is alias for list-workspaces
+bw ls "name:my-workspace-*" "alias:my-alias-*" "path:packages/**/*" # accepts workspace patterns
+
+# info includes the name, aliases, path, etc.
+bw workspace-info my-workspace
+bw info my-workspace --json --pretty # info is alias for workspace-info
+
+# info includes the script name and workspaces that have it in their package.json "scripts" field
+bw script-info my-script --json --pretty
+
+# run the package.json "lint" script for all workspaces that have it
+bw run-script lint
+
+# run is alias for run-script
+# run the package.json "lint" script for workspaces using matching specifiers
+bw run lint my-workspace-name "alias:my-alias-pattern-*" "path:my-glob/**/*" # accepts workspace patterns
+
+# A workspace's script will wait until any workspaces it depends on have completed
+# Similar to Bun's --filter behavior
+bw run lint --dep-order
+
+# Continue running scripts even if a dependency fails
+bw run lint --dep-order --ignore-dep-failure
+
+# special root workspace selector (works even if root workspace is not included)
+bw run lint @root
+
+# Scripts run in parallel by default
+bw run lint --parallel=false # Run in series
+
+# Default can be overridden by config or env var BW_PARALLEL_MAX_DEFAULT
+bw run lint --parallel # default "auto", os.availableParallelism()
+bw run lint --parallel=2 # Run in parallel with a max of 2 concurrent scripts
+bw run lint --parallel=50% # 50% of os.availableParallelism()
+bw run lint --parallel=unbounded # run all in one batch
+
+# add args to the script command
+bw run lint --args="--my-arg=value"
+bw run lint --args="--my-arg=<workspaceName>" # use the workspace name in args
+
+# run the script as an inline command from the workspace directory
+bw run "bun build" --inline
+bw run "bun build" --inline --inline-name="my-script"
+bw run "bun build" --inline --shell=system # use the system shell
+
+# Use the grouped output style (default when on a TTY)
+bw run my-script --output-style=grouped
+
+# Set the max preview lines for script output in grouped output style
+bw run my-script --output-style=grouped --grouped-lines=auto
+bw run my-script --output-style=grouped --grouped-lines=10
+
+# Use simple script output with workspace prefixes (default when not on a TTY)
+bw run my-script --output-style=prefixed
+
+# Use the plain output style (no workspace prefixes)
+bw run my-script --output-style=plain
+
+# List affected workspaces (default: git diff HEAD vs the configured base ref, "main" by default)
+bw list-affected
+bw ls-affected # alias
+
+# Compare specific git refs
+bw ls-affected --base=my-branch-a --head=my-branch-b
+bw ls-affected -B my-branch-a -H my-branch-b # short forms
+
+# Resolve inputs for a specific script (uses scripts[name].inputs when configured)
+bw ls-affected --script=build
+
+# Ignore some uncommitted changes (uncommitted included by default)
+bw ls-affected --ignore-uncommitted # all of: staged, unstaged, untracked
+bw ls-affected --ignore-untracked
+bw ls-affected --ignore-unstaged
+bw ls-affected --ignore-staged
+
+# Skip workspace dep cascade (only direct file/external-dep changes flag a workspace)
+bw ls-affected --ignore-workspace-deps
+
+# Skip lockfile-based external dep version tracking
+bw ls-affected --ignore-external-deps
+
+# Bypass git entirely with an explicit list of changed files
+# (paths, dirs, globs; '!' to exclude; whitespace-separated)
+bw ls-affected --files="packages/example/**/*.ts packages/example/my-file.json"
+bw ls-affected -F "packages/a/**/*.ts !packages/a/**/*.test.ts"
+
+# Per-workspace summary of why each workspace is affected
+bw ls-affected --explain
+bw ls-affected -e
+
+# Full per-file changes and dep cascade chain for each affected workspace
+bw ls-affected --explain --detailed
+bw ls-affected -e -D
+
+# JSON output (with --explain produces the full result object)
+bw ls-affected --json --pretty
+bw ls-affected --explain --json --pretty
+
+# Run a script across affected workspaces (accepts the same affected options
+# as ls-affected, plus the same script-execution options as run-script:
+# --parallel, --dep-order, --args, --output-style, --inline, etc.)
+bw run-affected build
+bw run-affected build --base=my-branch --ignore-uncommitted --dep-order
+bw run-affected build --files="packages/a/src/**/*.ts" --parallel=2
+bw run-affected "bun build" --inline --inline-name=build # inline command form
+
+### Global Options ###
+# Root directory of project:
+bw --cwd=/path/to/project ls
+bw -d /path/to/project ls
+
+# Include root workspace as a normal workspace (default false):
+bw --include-root ls
+bw -r ls
+bw --no-include-root ls # override config/env var setting
+
+# Log level (debug|info|warn|error|silent, default info)
+bw --log-level=silent ls
+bw -l silent ls
+```
+
+### API examples:
+
+The API is held in close parity with the CLI. It is developed first so that the CLI is a thin wrapper around the API.
+
+```typescript
+import { createFileSystemProject } from "bun-workspaces";
+
+const project = createFileSystemProject({
+  // the options object itself and its properties are optional
+  rootDirectory: "path/to/your/project",
+  includeRootWorkspace: false,
+});
+project.workspaces; // array of all workspaces in the project
+project.rootWorkspace; // the root workspace (available even when not included in the workspaces array)
+project.findWorkspaceByName("my-workspace"); // find a workspace by name
+project.findWorkspaceByAlias("my-alias"); // find a workspace by alias
+project.findWorkspaceByNameOrAlias("my-workspace-or-alias"); // find a workspace by name or alias
+project.findWorkspacesByPattern(
+  "my-workspace-name",
+  "my-workspace-alias",
+  "my-name-pattern-*",
+  "alias:my-alias-*",
+  "path:my-glob/**/*",
+); // find workspaces by pattern like the CLI
+project.runWorkspaceScript({
+  workspaceNameOrAlias: "my-workspace",
+  script: "lint",
+  inline: true,
+  // args can be a string or an array of strings
+  // if string, the argv will be parsed POSIX-style
+  args: "--my-arg=value",
+});
+project.runScriptAcrossWorkspaces({
+  script: "lint",
+  workspacePatterns: [
+    "alias:my-alias-pattern-*",
+    "path:my-glob/**/*",
+    "workspace-name-a",
+    "workspace-alias-b",
+  ],
+  parallel: true, // also could be { max: 2 }, max taking same options as seen in CLI examples above (e.g. "50%", "auto", etc.)
+  dependencyOrder: true,
+  ignoreDependencyFailure: true,
+  // same as for runWorkspaceScript
+  args: ["--my", "--appended", "--args"],
+  // Optional, callback when script starts, skips, or exits
+  onScriptEvent: (event, { workspace, exitResult }) => {
+    // event: "start", "skip", "exit"
+  },
+});
+
+// Determine affected workspaces — git mode (default)
+project.determineAffectedWorkspaces({
+  diffSource: "git",
+  // optional: resolve inputs for a specific script (uses scripts[name].inputs)
+  script: "build",
+  // optional: skip workspace dep cascade
+  ignoreWorkspaceDependencies: false,
+  // optional: skip lockfile-based external dep version tracking
+  ignoreExternalDependencies: false,
+  diffOptions: {
+    baseRef: "main", // default from config / "main"
+    headRef: "HEAD", // default
+    ignoreUncommitted: false, // staged + unstaged + untracked
+    ignoreUntracked: false,
+    ignoreUnstaged: false,
+    ignoreStaged: false,
+  },
+});
+
+// Determine affected workspaces — fileList mode (bypass git)
+project.determineAffectedWorkspaces({
+  diffSource: "fileList",
+  // paths, directories, or globs (relative to project root); '!' to exclude
+  changedFiles: ["packages/a/**/*.ts", "!packages/a/**/*.test.ts"],
+});
+
+// Run a script across affected workspaces. Accepts the same affected options
+// as determineAffectedWorkspaces, plus the script-execution options from
+// runScriptAcrossWorkspaces (parallel, dependencyOrder, args, onScriptEvent, etc.).
+project.runAffectedWorkspaceScript({
+  script: "build",
+  diffSource: "git",
+  diffOptions: { baseRef: "main", ignoreUncommitted: true },
+  parallel: { max: 2 },
+  dependencyOrder: true,
+  ignoreDependencyFailure: true,
+});
+```
+
+## The Workspace object
+
+```jsonc
+{
+  // The name of the workspace from its package.json
+  "name": "my-workspace",
+  // Whether the workspace is the root workspace
+  "isRoot": false,
+  // The relative path to the workspace from the project root
+  "path": "my/workspace/path",
+  // The glob pattern from the root package.json "workspaces" field
+  // that this workspace was matched from
+  "matchPattern": "my/workspace/pattern/*",
+  // The scripts available in the workspace's package.json
+  "scripts": ["my-script"],
+  // Aliases defined in workspace configuration (bw.workspace.jsonc/bw.workspace.json)
+  "aliases": ["my-alias"],
+  // Tags defined in workspace configuration
+  "tags": ["my-tag"],
+  // Names of other workspaces that this workspace depends on
+  "dependencies": ["my-dependency"],
+  // Names of other workspaces that depend on this workspace
+  "dependents": ["my-dependent"],
+  // Non-workspace package deps declared in package.json (across all four maps).
+  // `source` is one of "dependencies" | "devDependencies" | "peerDependencies" | "optionalDependencies".
+  // `version` is the package.json range, with `catalog:`/`catalog:<name>` resolved when possible.
+  // `catalog` is present when declared via a catalog ref.
+  "externalDependencies": [
+    { "name": "lodash", "version": "^4.17.0", "source": "dependencies" },
+    { "name": "typescript", "version": "^5.0.0", "source": "devDependencies" },
+    {
+      "name": "react",
+      "version": "^18.0.0",
+      "source": "dependencies",
+      "catalog": { "name": "" },
+    },
+  ],
+}
+```
+
+## Root config
+
+Optional project config can be placed in `bw.root.ts`/`bw.root.js`/`bw.root.jsonc`/`bw.root.json` in the root directory, or in the `"bw"` key of `package.json`.
+
+Config defaults here take precedence over environment variables. Explicit CLI arguments or API options take precedence over all other settings.
+
+```jsonc
+{
+  "defaults": {
+    "parallelMax": 5, // same options as seen in CLI examples above
+    "shell": "system", // "bun" or "system" (default "bun")
+    "includeRootWorkspace": true, // treat root package.json as a normal workspace
+    "affectedBaseRef": "main", // default git base ref for affected resolution (env: BW_AFFECTED_BASE_REF_DEFAULT)
+  },
+  "workspacePatternConfigs": [
+    // see Workspace Pattern Configs section below
+  ],
+}
+```
+
+### mergeRootConfig
+
+`mergeRootConfig` merges multiple root configs left to right. Later configs take precedence for scalar fields. `workspacePatternConfigs` entries are concatenated. Any argument may be a factory function `(prev: RootConfig) => RootConfig`.
+
+```ts
+import { mergeRootConfig } from "bun-workspaces/config";
+
+export default mergeRootConfig(
+  { defaults: { parallelMax: 4 } },
+  { defaults: { shell: "system" } },
+  (prevConfig) => ({ defaults: { includeRootWorkspace: true } }),
+);
+```
+
+## Workspace config
+
+Optional config can be placed in `bw.workspace.ts`/`bw.workspace.js`/`bw.workspace.jsonc`/`bw.workspace.json` in a workspace directory, or in the `"bw"` key of `package.json`.
+
+Aliases must be unique to each workspace and must not clash with other workspaces' `package.json` names.
+
+Tags are strings to group workspaces together; they do not need to be unique.
+
+```jsonc
+{
+  "alias": "my-alias", // can be array
+  "tags": ["my-tag"],
+  // Default inputs used to determine if the workspace is affected, applied to
+  // all scripts that don't configure their own inputs. See "Inputs" below.
+  "defaultInputs": {
+    "files": ["src/**/*.ts", "!src/**/*.test.ts"],
+    "workspacePatterns": ["tag:shared-lib"],
+    "externalDependencies": ["lodash", "react"],
+  },
+  "scripts": {
+    "lint": {
+      // set optional sorting order for scripts
+      "order": 1,
+    },
+    "build": {
+      // per-script inputs override defaultInputs for this script's affected resolution
+      "inputs": {
+        "files": ["src/**/*.ts", "/shared-types/**/*.ts"], // leading "/" = relative to the project root
+      },
+    },
+  },
+  "rules": {
+    "workspaceDependencies": {
+      // allowPatterns: only workspaces matching these patterns are permitted as dependencies
+      "allowPatterns": ["my-allow-pattern-*"],
+      // denyPatterns: workspaces matching these patterns are forbidden as dependencies.
+      // When combined with allowPatterns, deny filters within the allowed subset.
+      "denyPatterns": ["my-deny-pattern-*"],
+    },
+  },
+}
+```
+
+### Inputs
+
+The `defaultInputs` field (and the per-script `scripts[name].inputs` field) controls what counts as an input for [affected workspace](#affected-workspaces) resolution. Both have the same shape (`WorkspaceInputsConfig`):
+
+- `files` — file paths, directories, or globs relative to the workspace's directory. Leading `/` makes a pattern relative to the project root. Prefix with `!` to exclude. Only git-trackable files are matched. Default when not provided is `["."]` (everything in the workspace dir).
+- `workspacePatterns` — workspace patterns whose matched workspaces are treated as inputs (like dependencies, but without needing a real `package.json` dep edge).
+- `externalDependencies` — allowlist of package names that participate in lockfile-change detection. Omitted = all external deps participate; `[]` = none participate; non-empty list = only listed names participate (intersected with the workspace's actual external deps from `package.json`).
+
+Per-script `inputs` fully replaces `defaultInputs` for that script — the two are not merged. If a script has its own `inputs` field, `defaultInputs` is ignored for that script.
+
+### Workspace Dependency Rules
+
+Using the `rules.workspaceDependencies` field, you can define rules for which workspaces are allowed to be dependencies, using `allowPatterns`, `denyPatterns`, or both.
+
+`allowPatterns` defines the permitted subset of dependencies. `denyPatterns` forbids specific dependencies. When both are present, `denyPatterns` further filters within the subset permitted by `allowPatterns`.
+
+Workspace Patterns are used to match workspaces.
+
+### mergeWorkspaceConfig
+
+`mergeWorkspaceConfig` merges multiple workspace configs left to right. Arrays (`alias`, `tags`, `allowPatterns`, `denyPatterns`) are concatenated and deduplicated. Scalar fields later wins. `scripts` are deep-merged per key. Any argument may be a factory function `(prev: WorkspaceConfig) => WorkspaceConfig`.
+
+```ts
+import { mergeWorkspaceConfig } from "bun-workspaces/config";
+
+export default mergeWorkspaceConfig(
+  { alias: "a", tags: ["x"] },
+  { alias: "b", scripts: { build: { order: 1 } } },
+  (prevConfig) => ({ tags: ["y"] }),
+);
+// result: { alias: ["a", "b"], tags: ["x", "y"], scripts: { build: { order: 1 } } }
+```
+
+## Workspace Pattern Configs
+
+The root config's `workspacePatternConfigs` field applies workspace configs to groups of workspaces matched by [workspace patterns](/concepts/workspace-patterns). Entries are applied in order, left to right.
+
+Each entry's `config` is merged into the accumulated config of all matching workspaces using the same semantics as `mergeWorkspaceConfig`. The local workspace config (from `bw.workspace.*` or `package.json`) is always the starting base.
+
+Pattern matching reflects the accumulated state: aliases and tags added by earlier entries are visible to later entries' patterns.
+
+```ts
+import { defineRootConfig } from "bun-workspaces/config";
+
+export default defineRootConfig({
+  workspacePatternConfigs: [
+    {
+      patterns: ["path:packages/apps/**/*"],
+      config: { tags: ["app"] },
+    },
+    {
+      // "tag:app" matches because the entry above added it
+      patterns: ["tag:app"],
+      config: {
+        rules: { workspaceDependencies: { allowPatterns: ["tag:lib"] } },
+      },
+    },
+    {
+      patterns: ["tag:app"],
+      // Factory form: JS/TS only — receives static workspace data and accumulated config
+      config: (workspace, prevConfig) => ({
+        alias: workspace.name.replace(/^@my-scope\//, ""),
+      }),
+    },
+  ],
+});
+```
+
+### Factory function context (`RawWorkspace`)
+
+The factory `(workspace: RawWorkspace, prevConfig: ResolvedWorkspaceConfig) => WorkspaceConfig` receives:
+
+- `workspace.name` — package name from package.json
+- `workspace.isRoot` — whether this is the root workspace
+- `workspace.path` — relative path from project root
+- `workspace.matchPattern` — glob from root package.json `workspaces` field that matched
+- `workspace.scripts` — sorted list of script names from package.json
+- `workspace.dependencies` — names of workspace dependencies
+- `workspace.dependents` — names of workspaces that depend on this one
+
+`prevConfig` is the fully resolved workspace config at that point, including the local config and any configs applied by earlier pattern entries. It has `aliases: string[]`, `tags: string[]`, `scripts: Record<string, ScriptConfig>`, `rules: WorkspaceRules`, `defaultInputs?: WorkspaceInputsConfig`.
+
+## TypeScript/JSON Config Files
+
+### TypeScript
+
+`bw.workspace.ts`
+
+```ts
+import { defineWorkspaceConfig } from "bun-workspaces/config";
+
+export default defineWorkspaceConfig({
+  alias: "my-alias",
+  tags: ["my-tag"],
+});
+```
+
+`bw.root.ts`
+
+```ts
+import { defineRootConfig } from "bun-workspaces/config";
+
+export default defineRootConfig({
+  defaults: {
+    parallelMax: 5,
+  },
+});
+```
+
+<!-- bun-workspaces (npm package) agent documentation end -->

package/README.md

@@ -18,7 +18,7 @@ A [monorepo](http://sonarsource.com/resources/library/monorepo/) tool that enhan
 - Run one-off [**Bun Shell**](https://bun.com/docs/runtime/shell) commands in your workspaces 🐚
 - Use with Bun as your package manager for **Node** projects 🎁
 - Determine **affected workspaces** based on changed files 🕸️
-- Use the [MCP server](https://bunworkspaces.com/ai/mcp) to make your AI tooling aware of `bun-workspaces` and its documentation resources! 🛠️
+- AI: Provides an [AGENTS.md](https://bunworkspaces.com/ai/agents) file and an [MCP server](https://bunworkspaces.com/ai/mcp)! 🛠️
 
 To get started, all you need is a repo using Bun's workspaces feature for nested JavaScript/TypeScript packages. This adds enhanced features on top of plain workspaces.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bun-workspaces",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "A monorepo management tool for Bun, with a CLI and API to enhance Bun's native workspaces.",
   "license": "MIT",
   "exports": {

package/src/affected/fileAffectedWorkspaces.mjs

@@ -147,7 +147,10 @@ const matchChangedFilesForWorkspace = ({
   }
   return matchedFiles;
 };
-const resolveInputWorkspaceDependencies = ({ workspaceInputs }) => {
+const resolveInputWorkspaceDependencies = ({
+  workspaceInputs,
+  rootWorkspace,
+}) => {
   const inputDependenciesByName = new Map();
   const allWorkspaces = workspaceInputs.map(({ workspace }) => workspace);
   for (const { workspace, inputWorkspacePatterns } of workspaceInputs) {
@@ -158,6 +161,7 @@ const resolveInputWorkspaceDependencies = ({ workspaceInputs }) => {
     const matchedNames = matchWorkspacesByPatterns(
       inputWorkspacePatterns,
       allWorkspaces,
+      rootWorkspace,
     )
       .map((matchedWorkspace) => matchedWorkspace.name)
       .filter((matchedName) => matchedName !== workspace.name);
@@ -346,6 +350,7 @@ const getFileAffectedWorkspaces = async ({
   rootDirectory,
   workspaceInputs,
   changedFilePaths,
+  rootWorkspace,
   externalDepChangesByWorkspace = new Map(),
   ignoreWorkspaceDependencies = false,
 }) => {
@@ -375,6 +380,7 @@ const getFileAffectedWorkspaces = async ({
   });
   const inputDependenciesByName = resolveInputWorkspaceDependencies({
     workspaceInputs,
+    rootWorkspace,
   });
   const affectedSet = computeAffectedWorkspaceSet({
     workspaceInputs,

package/src/config/rootConfig/rootConfig.mjs

@@ -1,5 +1,5 @@
 import { resolveDefaultAffectedBaseRef } from "../../affected/affectedBaseRef.mjs";
-import validateRootConfig from "../../internal/generated/ajv/validateRootConfig.mjs";
+import { validate } from "../../internal/generated/ajv/validateRootConfig.mjs";
 import {
   determineParallelMax,
   resolveScriptShell,
@@ -9,16 +9,16 @@ import { executeValidator } from "../util/validateConfig.mjs";
 import { validateWorkspaceConfig } from "../workspaceConfig/workspaceConfig.mjs";
 import { ROOT_CONFIG_ERRORS } from "./errors.mjs";
 
-const rootConfig_validateRootConfig = (config) =>
+const validateRootConfig = (config) =>
   executeValidator(
-    validateRootConfig,
+    validate,
     "RootConfig",
     config,
     ROOT_CONFIG_ERRORS.InvalidRootConfig,
   );
 const createDefaultRootConfig = () => resolveRootConfig({});
 const resolveRootConfig = (config) => {
-  rootConfig_validateRootConfig(config);
+  validateRootConfig(config);
   for (const entry of config.workspacePatternConfigs ?? []) {
     if (typeof entry.config !== "function") {
       validateWorkspaceConfig(entry.config);
@@ -42,8 +42,4 @@ const resolveRootConfig = (config) => {
   };
 };
 
-export {
-  createDefaultRootConfig,
-  resolveRootConfig,
-  rootConfig_validateRootConfig as validateRootConfig,
-};
+export { createDefaultRootConfig, resolveRootConfig, validateRootConfig };

package/src/internal/generated/aiDocs/docs.mjs

@@ -1,4 +1,4 @@
-// This file is generated by scripts/generateMcpDocs.ts. Do not edit manually.
+// This file is generated by scripts/createPublicAgentDocs.ts. Do not edit manually.
 const DOC_OVERVIEW = `## Project Overview
 
 bun-workspaces is a CLI and TypeScript API to help manage Bun monorepos. It reads \`bun.lock\` to find all workspaces in the project. It is referred to as "bw" for short, which is also the recommended CLI alias. The overall goal is a monorepo tool that is more lightweight than others, with still powerful comparable features, requiring no special config to get started, only a standard Bun repo using workspaces.
@@ -9,12 +9,15 @@ Three main domain terms to know:
 - Workspace: a nested package within a project. The root package.json can count as a workspace as well, but by default, only nested packages are considered workspaces.
 - Script: an entry in the \`scripts\` field of a workspace's \`package.json\` file. bw can also run one-off commands known as "inline scripts," which can use the Bun shell or system shell (\`sh -c\` or \`cmd /d /s /c\` for windows).
 
-bw also supports **affected workspace** detection: given a set of changed files (from a git diff or an explicit list), it determines which workspaces are meaningfully changed. This drives \`bw list-affected\`/\`bw run-affected\` for orchestrating builds, tests, etc. across only the workspaces that need them.`;
+bw also supports **affected workspace** detection: given a set of changed files (from a git diff or an explicit list), it determines which workspaces are meaningfully changed. This drives \`bw list-affected\`/\`bw run-affected\` for orchestrating builds, tests, etc. across only the workspaces that need them.
+`;
 const DOC_CONCEPTS = `## Concepts
 
 ### Workspace patterns
 
-Many features accept a list of workspace patterns to match a subset of workspaces.
+Many features accept a list of workspace patterns to match a subset of workspaces:
+
+\`[not:][(name|alias|path|tag):][re:]<value>\`
 
 By default, a pattern matches the workspace name or alias: \`my-workspace-name\` or \`my-alias-name\`. Aliases are defined in config explained below.
 
@@ -24,8 +27,12 @@ Patterns can include a wildcard to match only by workspace name: \`my-workspace-
 - Path pattern specifier (supports glob): \`path:packages/**/*\`.
 - Name pattern specifier: \`name:my-workspace-*\`.
 - Tag pattern specifier: \`tag:my-tag\`.
-- Special root workspace selector: \`@root\`.
 - Any pattern can start with \`not:\` to negate the pattern. (e.g. "not:my-workspace-name", "not:tag:my-tag-\\*") This excludes workspaces that match any other present patterns from a result.
+- Regex pattern modifier can be applied before the pattern value: \`re:\` (e.g. "re:^my-workspace-.+" or "not:alias:re:^my-alias-.+")
+
+#### Special selectors
+
+- Special root workspace selector: \`@root\`. This is a reference to the root workspace, whether it's included in a Project's workspace list or not.
 
 ### Workspace Script Metadata
 
@@ -82,7 +89,8 @@ There are two diff sources:
 - **git** (default): diff \`HEAD\` against the configured base ref (default \`main\`, configurable via \`affectedBaseRef\` in the root config or \`BW_AFFECTED_BASE_REF_DEFAULT\` env var). Uncommitted changes (staged, unstaged, untracked) are included by default. Gitignored files never participate.
 - **fileList**: pass changed files explicitly (paths, dirs, or globs) — bypasses git entirely.
 
-Use \`--explain\` for a per-workspace summary of changed inputs and dep cascade reasons, and \`--explain --detailed\` for full per-file/edge breakdowns including the affected-dep chain.`;
+Use \`--explain\` for a per-workspace summary of changed inputs and dep cascade reasons, and \`--explain --detailed\` for full per-file/edge breakdowns including the affected-dep chain.
+`;
 const DOC_CLI = `### CLI examples:
 
 \`\`\`bash
@@ -208,7 +216,8 @@ bw --no-include-root ls # override config/env var setting
 # Log level (debug|info|warn|error|silent, default info)
 bw --log-level=silent ls
 bw -l silent ls
-\`\`\``;
+\`\`\`
+`;
 const DOC_API = `### API examples:
 
 The API is held in close parity with the CLI. It is developed first so that the CLI is a thin wrapper around the API.
@@ -337,7 +346,8 @@ project.runAffectedWorkspaceScript({
     },
   ],
 }
-\`\`\``;
+\`\`\`
+`;
 const DOC_CONFIG = `## Root config
 
 Optional project config can be placed in \`bw.root.ts\`/\`bw.root.js\`/\`bw.root.jsonc\`/\`bw.root.json\` in the root directory, or in the \`"bw"\` key of \`package.json\`.
@@ -522,6 +532,7 @@ export default defineRootConfig({
     parallelMax: 5,
   },
 });
-\`\`\``;
+\`\`\`
+`;
 
 export { DOC_API, DOC_CLI, DOC_CONCEPTS, DOC_CONFIG, DOC_OVERVIEW };

package/src/project/implementations/fileSystemProject/affectedWorkspaces.mjs

@@ -167,6 +167,7 @@ const determineAffectedWorkspaces = async (project, options) => {
         workspacesOptions: {
           workspaceInputs,
           workspaces: project.workspaces,
+          rootWorkspace: project.rootWorkspace,
           ignoreWorkspaceDependencies,
           ignoreExternalDependencies,
         },
@@ -209,6 +210,7 @@ const determineAffectedWorkspaces = async (project, options) => {
     rootDirectory: project.rootDirectory,
     workspaceInputs,
     changedFilePaths: expandedChangedFilePaths,
+    rootWorkspace: project.rootWorkspace,
     externalDepChangesByWorkspace,
     ignoreWorkspaceDependencies,
   });

package/src/project/implementations/projectBase.mjs

@@ -130,24 +130,18 @@ class ProjectBase {
     return this.workspaces.filter((workspace) => workspace.tags.includes(tag));
   }
   findWorkspacesByPattern(...workspacePatterns) {
-    const workspaces = [];
-    if (
-      workspacePatterns.includes(
-        /* inlined export .ROOT_WORKSPACE_SELECTOR */ "@root",
-      )
-    ) {
-      workspaces.push(this.rootWorkspace);
-      workspacePatterns = workspacePatterns.filter(
-        (pattern) =>
-          pattern !== /* inlined export .ROOT_WORKSPACE_SELECTOR */ "@root",
-      );
-    }
-    workspaces.push(
-      ...sortWorkspaces(
-        matchWorkspacesByPatterns(workspacePatterns, this.workspaces),
-      ),
+    const matched = matchWorkspacesByPatterns(
+      workspacePatterns,
+      this.workspaces,
+      this.rootWorkspace,
+    );
+    // Preserve historical ordering: root workspace first, then sorted others.
+    const rootName = this.rootWorkspace.name;
+    const rootMatch = matched.find((workspace) => workspace.name === rootName);
+    const rest = sortWorkspaces(
+      matched.filter((workspace) => workspace.name !== rootName),
     );
-    return workspaces;
+    return rootMatch ? [rootMatch, ...rest] : rest;
   }
   createScriptCommand(options) {
     validateJSTypes(

package/src/workspaces/applyWorkspacePatternConfigs.mjs

@@ -33,9 +33,14 @@ const applyWorkspacePatternConfigs = (
   workspaceMap,
   workspaceAliases,
   patternConfigs,
+  rootWorkspace,
 ) => {
   for (const entry of patternConfigs) {
-    const matched = matchWorkspacesByPatterns(entry.patterns, workspaces);
+    const matched = matchWorkspacesByPatterns(
+      entry.patterns,
+      workspaces,
+      rootWorkspace,
+    );
     for (const workspace of matched) {
       const mapEntry = workspaceMap[workspace.name];
       const prevConfig = mapEntry.config;

package/src/workspaces/dependencyGraph/validateDependencyRules.mjs

@@ -17,7 +17,7 @@ const getTransitiveDeps = (workspaceName, workspaceMap, chain, visited) => {
   }
   return result;
 };
-const validateWorkspaceDependencyRules = ({ workspaceMap }) => {
+const validateWorkspaceDependencyRules = ({ workspaceMap, rootWorkspace }) => {
   const violations = [];
   for (const [workspaceName, { config }] of Object.entries(workspaceMap)) {
     const rule = config.rules?.workspaceDependencies;
@@ -32,10 +32,15 @@ const validateWorkspaceDependencyRules = ({ workspaceMap }) => {
       const depWorkspace = workspaceMap[depName]?.workspace;
       if (!depWorkspace) continue;
       const chainStr = chain.join(" -> ");
+      // matchWorkspacesByPatterns can inject the root workspace when an
+      // "@root" pattern is present, even if it isn't in the input universe.
+      // We're only asking "does the single dep match?" so confirm by name.
       if (rule.allowPatterns) {
-        const isAllowed =
-          matchWorkspacesByPatterns(rule.allowPatterns, [depWorkspace]).length >
-          0;
+        const isAllowed = matchWorkspacesByPatterns(
+          rule.allowPatterns,
+          [depWorkspace],
+          rootWorkspace,
+        ).some((matched) => matched.name === depWorkspace.name);
         if (!isAllowed) {
           violations.push(
             `"${workspaceName}" violates workspaceDependencies rule: workspace "${depName}" is not permitted by allowPatterns (dependency chain: ${chainStr})`,
@@ -44,9 +49,11 @@ const validateWorkspaceDependencyRules = ({ workspaceMap }) => {
         }
       }
       if (rule.denyPatterns) {
-        const isDenied =
-          matchWorkspacesByPatterns(rule.denyPatterns, [depWorkspace]).length >
-          0;
+        const isDenied = matchWorkspacesByPatterns(
+          rule.denyPatterns,
+          [depWorkspace],
+          rootWorkspace,
+        ).some((matched) => matched.name === depWorkspace.name);
         if (isDenied) {
           violations.push(
             `"${workspaceName}" violates workspaceDependencies rule: workspace "${depName}" is denied by denyPatterns (dependency chain: ${chainStr})`,

package/src/workspaces/findWorkspaces.mjs

@@ -178,10 +178,12 @@ const findWorkspaces = ({
       workspaceMap,
       workspaceAliases,
       workspacePatternConfigs,
+      rootWorkspace,
     );
   }
   validateWorkspaceDependencyRules({
     workspaceMap,
+    rootWorkspace,
   });
   validateWorkspaceAliases(workspaces, workspaceAliases, rootWorkspace.name);
   logger.debug(

package/src/workspaces/workspacePattern.mjs

@@ -12,95 +12,183 @@ const WORKSPACE_PATTERN_NEGATION_PREFIXES = [
   WORKSPACE_PATTERN_NEGATION_SHORT_PREFIX,
 ];
 const WORKSPACE_PATTERN_SEPARATOR = ":";
+const WORKSPACE_PATTERN_REGEX_PREFIX = "re:";
+const validateRegexSource = (source, originalPattern) => {
+  try {
+    new RegExp(source);
+  } catch (cause) {
+    throw new WORKSPACE_PATTERN_ERRORS.InvalidWorkspacePattern(
+      `Invalid regex in workspace pattern "${originalPattern}": ${cause.message}`,
+    );
+  }
+};
 const parseWorkspacePattern = (pattern) => {
   const negationPrefix = WORKSPACE_PATTERN_NEGATION_PREFIXES.find((prefix) =>
     pattern.startsWith(prefix),
   );
   const isNegated = !!negationPrefix;
-  const patternValue = negationPrefix
+  const afterNegation = negationPrefix
     ? pattern.slice(negationPrefix.length)
     : pattern;
+  // The "@root" selector resolves to the project's root workspace. Recognized
+  // immediately after optional negation, so "not:@root" / "!@root" also work.
+  // A target-scoped value of "@root" (e.g. "name:@root") is treated as a literal,
+  // not a root selector.
+  if (afterNegation === /* inlined export .ROOT_WORKSPACE_SELECTOR */ "@root") {
+    return {
+      target: "default",
+      value: /* inlined export .ROOT_WORKSPACE_SELECTOR */ "@root",
+      isNegated,
+      isRegex: false,
+      isRootSelector: true,
+    };
+  }
+  // "re:" before any target consumes the rest as a regex against the default target.
+  // e.g. "re:path:foo" → default-target regex over literal source "path:foo".
+  if (afterNegation.startsWith(WORKSPACE_PATTERN_REGEX_PREFIX)) {
+    const value = afterNegation.slice(WORKSPACE_PATTERN_REGEX_PREFIX.length);
+    validateRegexSource(value, pattern);
+    return {
+      target: "default",
+      value,
+      isNegated,
+      isRegex: true,
+      isRootSelector: false,
+    };
+  }
   const target = TARGETS.find((target) =>
-    patternValue.startsWith(target + WORKSPACE_PATTERN_SEPARATOR),
+    afterNegation.startsWith(target + WORKSPACE_PATTERN_SEPARATOR),
   );
   if (!target) {
     return {
       target: "default",
-      value: patternValue,
+      value: afterNegation,
       isNegated,
+      isRegex: false,
+      isRootSelector: false,
     };
   }
-  const value = patternValue.slice(
+  const afterTarget = afterNegation.slice(
     target.length + WORKSPACE_PATTERN_SEPARATOR.length,
   );
+  if (afterTarget.startsWith(WORKSPACE_PATTERN_REGEX_PREFIX)) {
+    const value = afterTarget.slice(WORKSPACE_PATTERN_REGEX_PREFIX.length);
+    validateRegexSource(value, pattern);
+    return {
+      target,
+      value,
+      isNegated,
+      isRegex: true,
+      isRootSelector: false,
+    };
+  }
   return {
     target,
-    value,
+    value: afterTarget,
     isNegated,
+    isRegex: false,
+    isRootSelector: false,
   };
 };
-const stringifyWorkspacePattern = (pattern) => {
-  return `${pattern.target}${WORKSPACE_PATTERN_SEPARATOR}${pattern.value}`;
-};
 const PATTERN_TARGET_HANDLERS = {
-  default: (pattern, workspaces, wildcardRegex) => {
-    return workspaces.filter((workspace) => {
-      return (
-        (pattern.value.includes("*")
-          ? wildcardRegex.test(workspace.name)
-          : workspace.name === pattern.value) ||
-        workspace.aliases.some((alias) =>
-          pattern.value.includes("*")
-            ? wildcardRegex.test(alias)
-            : alias === pattern.value,
-        )
+  default: (pattern, workspaces) => {
+    // Plain string at the default target matches name OR alias. Wildcard and
+    // regex forms intentionally narrow to name only to avoid ambiguity — use
+    // an explicit "alias:" prefix to match aliases by wildcard/regex.
+    if (pattern.isRegex) {
+      const regex = new RegExp(pattern.value);
+      return workspaces.filter((workspace) => regex.test(workspace.name));
+    }
+    if (pattern.value.includes("*")) {
+      const wildcardRegex = createWildcardRegex(pattern.value);
+      return workspaces.filter((workspace) =>
+        wildcardRegex.test(workspace.name),
       );
-    });
+    }
+    return workspaces.filter(
+      (workspace) =>
+        workspace.name === pattern.value ||
+        workspace.aliases.includes(pattern.value),
+    );
   },
-  name: (pattern, workspaces, wildcardRegex) => {
-    return workspaces.filter((workspace) => {
-      return pattern.value.includes("*")
-        ? wildcardRegex.test(workspace.name)
-        : workspace.name === pattern.value;
-    });
+  name: (pattern, workspaces) => {
+    if (pattern.isRegex) {
+      const regex = new RegExp(pattern.value);
+      return workspaces.filter((workspace) => regex.test(workspace.name));
+    }
+    if (pattern.value.includes("*")) {
+      const wildcardRegex = createWildcardRegex(pattern.value);
+      return workspaces.filter((workspace) =>
+        wildcardRegex.test(workspace.name),
+      );
+    }
+    return workspaces.filter((workspace) => workspace.name === pattern.value);
   },
-  alias: (pattern, workspaces, wildcardRegex) => {
-    return workspaces.filter((workspace) => {
-      return pattern.value.includes("*")
-        ? workspace.aliases.some((alias) => wildcardRegex.test(alias))
-        : workspace.aliases.includes(pattern.value);
-    });
+  alias: (pattern, workspaces) => {
+    if (pattern.isRegex) {
+      const regex = new RegExp(pattern.value);
+      return workspaces.filter((workspace) =>
+        workspace.aliases.some((alias) => regex.test(alias)),
+      );
+    }
+    if (pattern.value.includes("*")) {
+      const wildcardRegex = createWildcardRegex(pattern.value);
+      return workspaces.filter((workspace) =>
+        workspace.aliases.some((alias) => wildcardRegex.test(alias)),
+      );
+    }
+    return workspaces.filter((workspace) =>
+      workspace.aliases.includes(pattern.value),
+    );
   },
   path: (pattern, workspaces) => {
+    if (pattern.isRegex) {
+      const regex = new RegExp(pattern.value);
+      // Normalize backslashes so regex sources stay portable: a single
+      // forward-slash-based regex works on both Windows and POSIX paths.
+      return workspaces.filter((workspace) =>
+        regex.test(workspace.path.replaceAll("\\", "/")),
+      );
+    }
     return workspaces.filter((workspace) =>
       new bun.Glob(pattern.value.replace(/\/+$/, "")).match(workspace.path),
     );
   },
-  tag: (pattern, workspaces, wildcardRegex) => {
+  tag: (pattern, workspaces) => {
+    if (pattern.isRegex) {
+      const regex = new RegExp(pattern.value);
+      return workspaces.filter((workspace) =>
+        workspace.tags.some((tag) => regex.test(tag)),
+      );
+    }
+    if (pattern.value.includes("*")) {
+      const wildcardRegex = createWildcardRegex(pattern.value);
+      return workspaces.filter((workspace) =>
+        workspace.tags.some((tag) => wildcardRegex.test(tag)),
+      );
+    }
     return workspaces.filter((workspace) =>
-      pattern.value.includes("*")
-        ? workspace.tags.some((tag) => wildcardRegex.test(tag))
-        : workspace.tags.includes(pattern.value),
+      workspace.tags.includes(pattern.value),
     );
   },
 };
-const matchWorkspacesByPattern = (pattern, workspaces) =>
-  PATTERN_TARGET_HANDLERS[pattern.target](
-    pattern,
-    workspaces,
-    createWildcardRegex(pattern.value),
-  );
-const matchWorkspacesByPatterns = (patterns, workspaces) => {
+const matchWorkspacesByPattern = (pattern, workspaces, rootWorkspace) => {
+  if (pattern.isRootSelector) {
+    return rootWorkspace ? [rootWorkspace] : [];
+  }
+  return PATTERN_TARGET_HANDLERS[pattern.target](pattern, workspaces);
+};
+const matchWorkspacesByPatterns = (patterns, workspaces, rootWorkspace) => {
   const parsedPatterns = patterns.map(parseWorkspacePattern);
   const excludePatterns = parsedPatterns.filter((pattern) => pattern.isNegated);
   const includePatterns = parsedPatterns.filter(
     (pattern) => !pattern.isNegated,
   );
   const excludeWorkspaces = excludePatterns.flatMap((pattern) =>
-    matchWorkspacesByPattern(pattern, workspaces),
+    matchWorkspacesByPattern(pattern, workspaces, rootWorkspace),
   );
   const includeWorkspaces = includePatterns.flatMap((pattern) =>
-    matchWorkspacesByPattern(pattern, workspaces),
+    matchWorkspacesByPattern(pattern, workspaces, rootWorkspace),
   );
   return includeWorkspaces.filter(
     (workspace, index, arr) =>
@@ -118,8 +206,8 @@ export {
   WORKSPACE_PATTERN_NEGATION_PREFIX,
   WORKSPACE_PATTERN_NEGATION_PREFIXES,
   WORKSPACE_PATTERN_NEGATION_SHORT_PREFIX,
+  WORKSPACE_PATTERN_REGEX_PREFIX,
   WORKSPACE_PATTERN_SEPARATOR,
   matchWorkspacesByPatterns,
   parseWorkspacePattern,
-  stringifyWorkspacePattern,
 };