bun-workspaces 1.8.2 → 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

@@ -2,25 +2,29 @@
 <img src="./workspaces/web/documentation-website/src/pages/public/images/png/bwunster-bg-banner-wide_3000x900.png" alt="bun-workspaces" width="100%" />
 </a>
 
-# bun-workspaces
+<br/>
 
-### [**See Full Documentation Here**: _https://bunworkspaces.com_](https://bunworkspaces.com)
+Full Documentation: [https://bunworkspaces.com](https://bunworkspaces.com)
 
-This is a CLI and TypeScript API to enhance your monorepo development with Bun's [native workspaces](https://bun.sh/docs/install/workspaces) feature for nested JavaScript/TypeScript packages.
+Changelog: [GitHub Releases](https://github.com/bun-workspaces/bun-workspaces/releases)
 
-- Works right away, with no boilerplate required 🍔🍴
-- Get metadata about your monorepo 🤖
-- Orchestrate your workspaces' `package.json` scripts 📋
-- Run inline [Bun Shell](https://bun.com/docs/runtime/shell) scripts in workspaces 🐚
-- Use the [MCP server](https://bunworkspaces.com/ai/mcp) for your AI tooling to learn how to use `bun-workspaces` and add project metadata to context! 🛠️
+# bun-workspaces
 
-This is a tool to help manage a Bun monorepo, offering features beyond what [Bun's --filter feature](https://bun.com/docs/pm/filter) can do. It can be used to get a variety of metadata about your project and run scripts across your workspaces with advanced control.
+A [monorepo](http://sonarsource.com/resources/library/monorepo/) tool that enhances native [Bun workspaces](https://bun.sh/docs/install/workspaces).
 
-To get started, all you need is a repo using [Bun's workspaces feature](https://bun.sh/docs/install/workspaces) for nested JavaScript/TypeScript packages.
+- Works right away, with **no boilerplate required** 🍽️
+- Get **rich metadata** about your monorepo 🤖
+- **Orchestrate** your workspaces' package.json scripts 🎻
+- 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 🕸️
+- AI: Provides an [AGENTS.md](https://bunworkspaces.com/ai/agents) file and an [MCP server](https://bunworkspaces.com/ai/mcp)! 🛠️
 
-This package is unopinionated and works with any project structure you want. Think of this as a power suit you can snap onto native workspaces, rather than whole new monorepo framework.
+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.
 
-Start running some [CLI commands](https://bunworkspaces.com/cli) right away in your repo, or take full advantage of the [scripting API](https://bunworkspaces.com/api) and its features.
+Start running some [CLI commands](https://bunworkspaces.com/cli) right away in your repo, or take full advantage of the [TypeScript API](https://bunworkspaces.com/api) and its features.
+
+This package is unopinionated and works with any project structure you want. Think of this as a power suit you can snap onto native workspaces, rather than whole new monorepo framework.
 
 ## Quick Start
 
@@ -101,6 +105,18 @@ 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 based on git diff (main vs. HEAD when not configured)
+bw list-affected
+
+# Set the git base and head for comparison
+bw list-affected --base=my-branch-a --head=my-branch-b
+
+# See detailed reasons for affected workspaces
+bw list-affected --explain --detailed
+
+# Run a script across the workspaces affected by a change
+bw run-affected my-script
+
 # Silence all output of the run command
 bw --log-level=silent run my-script --output-style=none
 
@@ -262,9 +278,26 @@ import { defineWorkspaceConfig } from "bun-workspaces/config";
 export default defineWorkspaceConfig({
   alias: "my-web-app", // shorthand name; use array for multiple
   tags: ["app", "frontend"],
+  // Optional, for configuring affected workspace resolution inputs
+  // Applies to all scripts that don't configure their own inputs
+  defaultInputs: {
+    // File paths, directory paths, or globs relative to the workspace's path.
+    // Default is all git-trackable files in the workspace directory.
+    files: ["src/**/*.ts", "!src/**/*.test.ts"],
+    // Workspaces to treat like dependencies that aren't package.json dependencies
+    workspacePatterns: ["tag:lib"],
+    // Dependency names (e.g. "react") to treat as dependencies (default: all)
+    externalDependencies: ["react"],
+  },
   scripts: {
     // lower order runs first in sequenced script execution
-    build: { order: 1 },
+    build: {
+      // Optional, for setting the default script execution order
+      order: 1,
+      // Optional, for configuring affected workspace resolution inputs
+      // Applies to the build script only
+      inputs: { files: ["src/**/*.ts"] },
+    },
     test: { order: 2 },
   },
   rules: {
@@ -320,6 +353,11 @@ export default defineRootConfig({
       // "tag:app" matches because the first entry added it
       patterns: ["tag:app"],
       config: {
+        // Inputs always override previous entries instead of deep merging
+        defaultInputs: { files: ["src/**/*.ts"] },
+        scripts: {
+          build: { order: 1, inputs: { files: ["src/**/*.ts"] } },
+        },
         rules: {
           workspaceDependencies: {
             allowPatterns: ["tag:lib"], // apps may only depend on libs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bun-workspaces",
-  "version": "1.8.2",
+  "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": {