bun-workspaces 1.8.1 → 1.9.0

package/src/cli/index.d.ts

@@ -42,6 +42,47 @@ export type WorkspaceDependenciesRule = {
 export type WorkspaceRules = {
   workspaceDependencies?: WorkspaceDependenciesRule;
 };
+/**
+ * Configured inputs for a script.
+ *
+ * These can be used to specify the files and workspace patterns
+ * that should be considered inputs for the script.
+ *
+ * The default inputs when not provided are all git-trackable files in the workspace.
+ */
+export type WorkspaceInputsConfig = {
+  /**
+   * File paths, directory paths, or globs relative to the workspace's path.
+   *
+   * Prefix with `!` to exclude.
+   *
+   * The default inputs when not provided are all git-trackable files in the workspace.
+   *
+   * Files that are not git-trackable are not considered inputs.
+   *
+   * Paths with a leading `/` are relative to the project root.
+   */
+  files?: string[];
+  /**
+   * Matched workspaces are treated as inputs for the script.
+   *
+   * For example, when workspaces are provided here, they will
+   * be treated like dependencies in the affected workspace resolution.
+   */
+  workspacePatterns?: string[];
+  /**
+   * Filters which of the workspace's declared external (non-workspace) deps
+   * participate in lockfile-change detection.
+   *
+   * - When omitted, every declared external dep participates (default).
+   * - When set to an empty array, no external deps participate (the workspace
+   *   will not be flagged from a lockfile change unless something else makes it so).
+   * - When set to a non-empty list of package names, only the listed names
+   *   participate. Names not present in the workspace's actual
+   *   `externalDependencies` are silently ignored.
+   */
+  externalDependencies?: string[];
+};
 /** Configuration that applies to a specific package.json script */
 export type ScriptConfig = {
   /**
@@ -51,6 +92,15 @@ export type ScriptConfig = {
    * of their relative path from the project root.
    */
   order?: number;
+  /**
+   * Inputs for the script.
+   *
+   * These can be used to specify the files and workspace patterns
+   * that should be considered inputs for the script.
+   *
+   * The default inputs when not provided are all git-trackable files in the workspace.
+   */
+  inputs?: WorkspaceInputsConfig;
 };
 /** Configuration that applies to a specific workspace */
 export type WorkspaceConfig = {
@@ -75,12 +125,18 @@ export type WorkspaceConfig = {
    * Rules that validate the workspace.
    */
   rules?: WorkspaceRules;
+  /**
+   * The default inputs for the workspace
+   * applied to all scripts that don't configure their own inputs.
+   */
+  defaultInputs?: WorkspaceInputsConfig;
 };
 export type ResolvedWorkspaceConfig = {
   aliases: string[];
   tags: string[];
   scripts: Record<string, ScriptConfig>;
   rules: WorkspaceRules;
+  defaultInputs?: WorkspaceInputsConfig;
 };
 /** Static workspace context passed to a {@link WorkspacePatternConfigFactory}.
  * Contains only the immutable, package.json-derived fields — not config-derived fields like aliases or tags. */
@@ -112,6 +168,7 @@ export type ResolvedRootConfig = {
     shell: ScriptShellOption;
     /** `undefined` means the value was not set in the input config */
     includeRootWorkspace: boolean | undefined;
+    affectedBaseRef: string;
   };
   workspacePatternConfigs: WorkspacePatternConfigEntry[];
 };
@@ -143,6 +200,39 @@ export interface MultiProcessOutput<Metadata extends object = object> {
   bytes(): BytesOutput<Metadata>;
   text(): TextOutput<Metadata>;
 }
+/** Catalog reference info attached to an `ExternalDependency` that uses a `catalog:` ref */
+export type ExternalDependencyCatalog = {
+  /** Catalog name from the `catalog:<name>` ref. Empty string for the default catalog (`catalog:`). */
+  name: string;
+};
+declare const EXTERNAL_DEPENDENCY_SOURCES: readonly [
+  "dependencies",
+  "devDependencies",
+  "peerDependencies",
+  "optionalDependencies",
+];
+export type ExternalDependencySource =
+  (typeof EXTERNAL_DEPENDENCY_SOURCES)[number];
+/** A non-workspace package the workspace declares (resolved via package.json + catalogs) */
+export type ExternalDependency = {
+  /** The package name as it appears in `node_modules` */
+  name: string;
+  /**
+   * Version specifier from `package.json`, with `catalog:`/`catalog:<name>` references
+   * resolved to the catalog's value. If the catalog reference cannot be resolved, the
+   * literal `catalog:` / `catalog:<name>` string is preserved.
+   */
+  version: string;
+  /**
+   * Which `package.json` dependency map this dep was declared in. When a dep
+   * appears in multiple maps, `dependencies` wins over the others, and any
+   * non-`devDependencies` source wins over `devDependencies`. One entry per
+   * unique name.
+   */
+  source: ExternalDependencySource;
+  /** Present when the dep was declared via a `catalog:` reference in `package.json` */
+  catalog?: ExternalDependencyCatalog;
+};
 /** Metadata about a nested package within a Bun monorepo */
 export type Workspace = {
   /** The name of the workspace from its `package.json` */
@@ -163,6 +253,8 @@ export type Workspace = {
   dependencies: string[];
   /** Names of workspaces that depend on this workspace */
   dependents: string[];
+  /** Non-workspace package dependencies declared by this workspace */
+  externalDependencies: ExternalDependency[];
 };
 declare const WORKSPACE_SCRIPT_COMMAND_METHODS: readonly ["cd", "filter"];
 export type WorkspaceScriptCommandMethod =
@@ -295,134 +387,6 @@ declare abstract class ProjectBase implements Project {
     options: CreateProjectScriptCommandOptions,
   ): CreateProjectScriptCommandResult;
 }
-/** Arguments for {@link createFileSystemProject} */
-export type CreateFileSystemProjectOptions = {
-  /** The directory containing the root package.json. Often the same root as a git repository. Relative to process.cwd(). The default is process.cwd(). */
-  rootDirectory?: string;
-  /**
-   * The name of the project.
-   *
-   * By default will use the root package.json name
-   */
-  name?: string;
-  /** Whether to include the root workspace as a normal workspace. This overrides any config or env var settings. */
-  includeRootWorkspace?: boolean;
-};
-export type InlineScriptOptions = {
-  /** A name to act as a label for the inline script */
-  scriptName?: string;
-  /** Whether to use the system shell or Bun shell */
-  shell?: ShellOption;
-};
-/** Arguments for `FileSystemProject.runWorkspaceScript` */
-export type RunWorkspaceScriptOptions = {
-  /** The name of the workspace to run the script in */
-  workspaceNameOrAlias: string;
-  /** The name of the script to run, or an inline command when `inline` is true */
-  script: string;
-  /** Whether to run the script as an inline command */
-  inline?: boolean | InlineScriptOptions;
-  /** The arguments to append to the script command. If passed as a string, the argv will be parsed POSIX-style */
-  args?: string | string[];
-  /** Set to `true` to ignore all output from the script. This saves memory when you don't need script output. */
-  ignoreOutput?: boolean;
-};
-/** Metadata associated with a workspace script */
-export type RunWorkspaceScriptMetadata = {
-  /** The workspace that the script was run in */
-  workspace: Workspace;
-};
-export type RunWorkspaceScriptExit = Simplify<
-  RunScriptExit<RunWorkspaceScriptMetadata>
->;
-export type RunWorkspaceScriptProcessOutput = MultiProcessOutput<
-  RunWorkspaceScriptMetadata & {
-    streamName: OutputStreamName;
-  }
->;
-/** Result of `FileSystemProject.runWorkspaceScript` */
-export type RunWorkspaceScriptResult = {
-  /** Use to get the output of the script */
-  output: RunWorkspaceScriptProcessOutput;
-  /** The exit result of the script */
-  exit: Promise<RunWorkspaceScriptExit>;
-};
-export type ParallelOption = boolean | RunScriptsParallelOptions;
-export type ScriptEventMetadata = {
-  /** The workspace that the script event occurred in */
-  workspace: Workspace;
-  /** The exit result of the script */
-  exitResult: RunScriptExit<RunWorkspaceScriptMetadata> | null;
-};
-export type OnScriptEventCallback = (
-  /** The event that occurred */
-  event: ScriptEventName,
-  /** The metadata for the script event */
-  metadata: ScriptEventMetadata,
-) => unknown;
-/** Arguments for `FileSystemProject.runScriptAcrossWorkspaces` */
-export type RunScriptAcrossWorkspacesOptions = {
-  /**
-   * Workspace names, aliases, or patterns including a wildcard.
-   *
-   * When not provided, all workspaces that the script can be ran in will be used.
-   */
-  workspacePatterns?: string[];
-  /** The name of the script to run, or an inline command when `inline` is true */
-  script: string;
-  /** Whether to run the script as an inline command */
-  inline?: boolean | InlineScriptOptions;
-  /** The arguments to append to the script command. If passed as a string, the argv will be parsed POSIX-style */
-  args?: string | string[];
-  /** Whether to run the scripts in parallel (default: `true`). Pass `false` to run in series. */
-  parallel?: ParallelOption;
-  /** When `true`, run scripts so that dependent workspaces run only after their dependencies */
-  dependencyOrder?: boolean;
-  /** When `true`, continue running scripts even if a dependency fails (Only relevant when `dependencyOrder` is `true`) */
-  ignoreDependencyFailure?: boolean;
-  /** Set to `true` to ignore all output from the scripts. This saves memory when you don't need script output. */
-  ignoreOutput?: boolean;
-  /** Callback to invoke when a script event occurs (start, skip, exit) */
-  onScriptEvent?: OnScriptEventCallback;
-};
-export type RunScriptAcrossWorkspacesSummary = Simplify<
-  RunScriptsSummary<RunWorkspaceScriptMetadata>
->;
-export type RunScriptAcrossWorkspacesOutput = MultiProcessOutput<
-  RunWorkspaceScriptMetadata & {
-    streamName: OutputStreamName;
-  }
->;
-/** Result of `FileSystemProject.runScriptAcrossWorkspaces` */
-export type RunScriptAcrossWorkspacesResult = {
-  /** Use to get the output of the scripts */
-  output: RunScriptAcrossWorkspacesOutput;
-  /** The summary of the script run with exit details for each workspace */
-  summary: Promise<RunScriptAcrossWorkspacesSummary>;
-  /** The workspaces targeted */
-  workspaces: Workspace[];
-};
-declare class _FileSystemProject extends ProjectBase implements Project {
-  #private;
-  readonly rootDirectory: string;
-  readonly workspaces: Workspace[];
-  readonly name: string;
-  readonly sourceType = "fileSystem";
-  readonly config: ProjectConfig;
-  readonly rootWorkspace: Workspace;
-  constructor(options: CreateFileSystemProjectOptions);
-  runWorkspaceScript(
-    options: RunWorkspaceScriptOptions,
-  ): RunWorkspaceScriptResult;
-  runScriptAcrossWorkspaces(
-    options: RunScriptAcrossWorkspacesOptions,
-  ): RunScriptAcrossWorkspacesResult;
-}
-/** An implementation of {@link Project} that is created from a root directory in the file system. */
-export type FileSystemProject = Simplify<_FileSystemProject>;
-declare const LOG_LEVELS: readonly ["debug", "info", "warn", "error"];
-export type LogLevel = (typeof LOG_LEVELS)[number];
-export type LogLevelSetting = LogLevel | "silent";
 export interface CliCommandConfig {
   command: string;
   isGlobal: boolean;
@@ -477,7 +441,7 @@ export declare const CLI_COMMANDS_CONFIG: {
     readonly options: {
       readonly workspacePatterns: {
         readonly flags: ["-W", "--workspace-patterns <patterns>"];
-        readonly description: "Workspace patterns to match, separated by spaces";
+        readonly description: "Workspace patterns to match, separated by whitespace. Use backslashes to escape spaces if needed.";
       };
       readonly nameOnly: {
         readonly flags: ["-n", "--name-only"];
@@ -592,6 +556,70 @@ export declare const CLI_COMMANDS_CONFIG: {
     readonly description: "Start the bun-workspaces MCP (Model Context Protocol) server over stdio";
     readonly options: {};
   };
+  readonly listAffected: {
+    readonly command: "list-affected";
+    readonly isGlobal: false;
+    readonly aliases: ["ls-affected"];
+    readonly description: "List workspaces affected by a set of changed files (git or file list)";
+    readonly options: {
+      readonly base: {
+        readonly flags: ["-B", "--base <ref>"];
+        readonly description: "Git base ref to diff against (default is main if not configured). Cannot be used with --files";
+      };
+      readonly head: {
+        readonly flags: ["-H", "--head <ref>"];
+        readonly description: "Git head ref to diff against (default: HEAD). Cannot be used with --files";
+      };
+      readonly files: {
+        readonly flags: ["-F", "--files <files>"];
+        readonly description: "Changed files (paths/dirs/globs, '!' to exclude), separated by spaces. Use backslashes to escape spaces if needed. Bypasses git, so cannot be used with --base or --head.";
+      };
+      readonly script: {
+        readonly flags: ["-S", "--script <script>"];
+        readonly description: "Resolve inputs for the named script";
+      };
+      readonly ignoreUntracked: {
+        readonly flags: ["--ignore-untracked"];
+        readonly description: "Exclude untracked files";
+      };
+      readonly ignoreUnstaged: {
+        readonly flags: ["--ignore-unstaged"];
+        readonly description: "Exclude unstaged files";
+      };
+      readonly ignoreStaged: {
+        readonly flags: ["--ignore-staged"];
+        readonly description: "Exclude staged files";
+      };
+      readonly ignoreUncommitted: {
+        readonly flags: ["--ignore-uncommitted"];
+        readonly description: "Exclude all uncommitted changes (staged, unstaged, untracked)";
+      };
+      readonly ignoreWorkspaceDeps: {
+        readonly flags: ["--ignore-workspace-deps"];
+        readonly description: "Ignore workspace dependencies derived from package.json files";
+      };
+      readonly ignoreExternalDeps: {
+        readonly flags: ["--ignore-external-deps"];
+        readonly description: "Ignore changes to external dependencies (e.g. npm packages) versions in bun.lock";
+      };
+      readonly explain: {
+        readonly flags: ["-e", "--explain"];
+        readonly description: "Include changed-file counts and dependency reasons. With --json, outputs the full result object";
+      };
+      readonly detailed: {
+        readonly flags: ["-D", "--detailed"];
+        readonly description: "With --explain, render full per-file data and dependency edge chains";
+      };
+      readonly json: {
+        readonly flags: readonly ["-j", "--json"];
+        readonly description: "Output as JSON";
+      };
+      readonly pretty: {
+        readonly flags: readonly ["-p", "--pretty"];
+        readonly description: "Pretty print JSON";
+      };
+    };
+  };
   readonly runScript: {
     readonly command: "run-script [script] [workspacePatterns...]";
     readonly isGlobal: false;
@@ -600,11 +628,106 @@ export declare const CLI_COMMANDS_CONFIG: {
     readonly options: {
       readonly script: {
         readonly flags: ["-S", "--script <script>"];
-        readonly description: "The script to run.";
+        readonly description: "The script to run. (Alternative to positional argument)";
       };
       readonly workspacePatterns: {
         readonly flags: ["-W", "--workspace-patterns <patterns>"];
-        readonly description: "Workspace patterns to match, separated by spaces.";
+        readonly description: "Workspace patterns to match, separated by spaces. (Alternative to positional arguments)";
+      };
+      readonly parallel: {
+        readonly flags: ["-P", "--parallel [max]"];
+        readonly description: 'Run the scripts in parallel. Pass "false" for series, or a concurrency limit as a number, percentage ("50%"), "auto", "default", or"unbounded"';
+      };
+      readonly args: {
+        readonly flags: ["-a", "--args <args>"];
+        readonly description: "Args to append to the script command";
+      };
+      readonly outputStyle: {
+        readonly flags: ["-o", "--output-style <style>"];
+        readonly description: "The output style to use";
+        readonly values: ["grouped", "prefixed", "plain", "none"];
+      };
+      readonly groupedLines: {
+        readonly flags: ["-L", "--grouped-lines <count>"];
+        readonly description: 'With grouped output, the max preview lines (number or "auto", default "auto")';
+      };
+      readonly noPrefix: {
+        readonly flags: ["-N", "--no-prefix"];
+        readonly description: "(DEPRECATED) Use --output-style=plain instead";
+        readonly deprecated: true;
+      };
+      readonly inline: {
+        readonly flags: ["-i", "--inline"];
+        readonly description: "Run the script as an inline command from the workspace directory";
+      };
+      readonly inlineName: {
+        readonly flags: ["-I", "--inline-name <name>"];
+        readonly description: "An optional name for the script when --inline is passed";
+      };
+      readonly shell: {
+        readonly flags: ["-s", "--shell <shell>"];
+        readonly values: ["bun", "system", "default"];
+        readonly description: "When using --inline, the shell to use to run the script";
+      };
+      readonly depOrder: {
+        readonly flags: ["-d", "--dep-order"];
+        readonly description: "Scripts for dependent workspaces run only after their dependencies";
+      };
+      readonly ignoreDepFailure: {
+        readonly flags: ["-f", "--ignore-dep-failure"];
+        readonly description: "In dependency order, continue running scripts even if a dependency fails";
+      };
+      readonly jsonOutfile: {
+        readonly flags: ["-j", "--json-outfile <file>"];
+        readonly description: "Output results in a JSON file";
+      };
+    };
+  };
+  readonly runAffected: {
+    readonly command: "run-affected [script]";
+    readonly isGlobal: false;
+    readonly aliases: [];
+    readonly description: "Run a script across the workspaces affected by a set of changed files (git or file list)";
+    readonly options: {
+      readonly script: {
+        readonly flags: ["-S", "--script <script>"];
+        readonly description: "The script to run. (Alternative to positional argument)";
+      };
+      readonly base: {
+        readonly flags: ["-B", "--base <ref>"];
+        readonly description: "Git base ref to diff against (default is main if not configured). Cannot be used with --files";
+      };
+      readonly head: {
+        readonly flags: ["-H", "--head <ref>"];
+        readonly description: 'Git head ref to diff against (default "HEAD"). Cannot be used with --files';
+      };
+      readonly files: {
+        readonly flags: ["-F", "--files <files>"];
+        readonly description: "Changed files (paths/dirs/globs, '!' to exclude), separated by whitespace. Use backslashes to escape spaces if needed. Bypasses git, so cannot be used with --base or --head.";
+      };
+      readonly ignoreUntracked: {
+        readonly flags: ["--ignore-untracked"];
+        readonly description: "Exclude untracked files";
+      };
+      readonly ignoreUnstaged: {
+        readonly flags: ["--ignore-unstaged"];
+        readonly description: "Exclude unstaged files";
+      };
+      readonly ignoreStaged: {
+        readonly flags: ["--ignore-staged"];
+        readonly description: "Exclude staged files";
+      };
+      readonly ignoreUncommitted: {
+        readonly flags: ["--ignore-uncommitted"];
+        readonly description: "Exclude all uncommitted changes (staged, unstaged, untracked)";
+      };
+      readonly ignoreWorkspaceDeps: {
+        readonly flags: ["--ignore-workspace-deps"];
+        readonly description: "Ignore workspace dependencies derived from package.json files";
+      };
+      readonly ignoreExternalDeps: {
+        readonly flags: ["--ignore-external-deps"];
+        readonly description: "Ignore changes to external dependencies (e.g. npm packages) versions in bun.lock";
       };
       readonly parallel: {
         readonly flags: ["-P", "--parallel [max]"];
@@ -681,7 +804,7 @@ export declare const getCliCommandConfig: (commandName: CliCommandName) =>
       readonly options: {
         readonly workspacePatterns: {
           readonly flags: ["-W", "--workspace-patterns <patterns>"];
-          readonly description: "Workspace patterns to match, separated by spaces";
+          readonly description: "Workspace patterns to match, separated by whitespace. Use backslashes to escape spaces if needed.";
         };
         readonly nameOnly: {
           readonly flags: ["-n", "--name-only"];
@@ -796,6 +919,70 @@ export declare const getCliCommandConfig: (commandName: CliCommandName) =>
       readonly description: "Start the bun-workspaces MCP (Model Context Protocol) server over stdio";
       readonly options: {};
     }
+  | {
+      readonly command: "list-affected";
+      readonly isGlobal: false;
+      readonly aliases: ["ls-affected"];
+      readonly description: "List workspaces affected by a set of changed files (git or file list)";
+      readonly options: {
+        readonly base: {
+          readonly flags: ["-B", "--base <ref>"];
+          readonly description: "Git base ref to diff against (default is main if not configured). Cannot be used with --files";
+        };
+        readonly head: {
+          readonly flags: ["-H", "--head <ref>"];
+          readonly description: "Git head ref to diff against (default: HEAD). Cannot be used with --files";
+        };
+        readonly files: {
+          readonly flags: ["-F", "--files <files>"];
+          readonly description: "Changed files (paths/dirs/globs, '!' to exclude), separated by spaces. Use backslashes to escape spaces if needed. Bypasses git, so cannot be used with --base or --head.";
+        };
+        readonly script: {
+          readonly flags: ["-S", "--script <script>"];
+          readonly description: "Resolve inputs for the named script";
+        };
+        readonly ignoreUntracked: {
+          readonly flags: ["--ignore-untracked"];
+          readonly description: "Exclude untracked files";
+        };
+        readonly ignoreUnstaged: {
+          readonly flags: ["--ignore-unstaged"];
+          readonly description: "Exclude unstaged files";
+        };
+        readonly ignoreStaged: {
+          readonly flags: ["--ignore-staged"];
+          readonly description: "Exclude staged files";
+        };
+        readonly ignoreUncommitted: {
+          readonly flags: ["--ignore-uncommitted"];
+          readonly description: "Exclude all uncommitted changes (staged, unstaged, untracked)";
+        };
+        readonly ignoreWorkspaceDeps: {
+          readonly flags: ["--ignore-workspace-deps"];
+          readonly description: "Ignore workspace dependencies derived from package.json files";
+        };
+        readonly ignoreExternalDeps: {
+          readonly flags: ["--ignore-external-deps"];
+          readonly description: "Ignore changes to external dependencies (e.g. npm packages) versions in bun.lock";
+        };
+        readonly explain: {
+          readonly flags: ["-e", "--explain"];
+          readonly description: "Include changed-file counts and dependency reasons. With --json, outputs the full result object";
+        };
+        readonly detailed: {
+          readonly flags: ["-D", "--detailed"];
+          readonly description: "With --explain, render full per-file data and dependency edge chains";
+        };
+        readonly json: {
+          readonly flags: readonly ["-j", "--json"];
+          readonly description: "Output as JSON";
+        };
+        readonly pretty: {
+          readonly flags: readonly ["-p", "--pretty"];
+          readonly description: "Pretty print JSON";
+        };
+      };
+    }
   | {
       readonly command: "run-script [script] [workspacePatterns...]";
       readonly isGlobal: false;
@@ -804,11 +991,106 @@ export declare const getCliCommandConfig: (commandName: CliCommandName) =>
       readonly options: {
         readonly script: {
           readonly flags: ["-S", "--script <script>"];
-          readonly description: "The script to run.";
+          readonly description: "The script to run. (Alternative to positional argument)";
         };
         readonly workspacePatterns: {
           readonly flags: ["-W", "--workspace-patterns <patterns>"];
-          readonly description: "Workspace patterns to match, separated by spaces.";
+          readonly description: "Workspace patterns to match, separated by spaces. (Alternative to positional arguments)";
+        };
+        readonly parallel: {
+          readonly flags: ["-P", "--parallel [max]"];
+          readonly description: 'Run the scripts in parallel. Pass "false" for series, or a concurrency limit as a number, percentage ("50%"), "auto", "default", or"unbounded"';
+        };
+        readonly args: {
+          readonly flags: ["-a", "--args <args>"];
+          readonly description: "Args to append to the script command";
+        };
+        readonly outputStyle: {
+          readonly flags: ["-o", "--output-style <style>"];
+          readonly description: "The output style to use";
+          readonly values: ["grouped", "prefixed", "plain", "none"];
+        };
+        readonly groupedLines: {
+          readonly flags: ["-L", "--grouped-lines <count>"];
+          readonly description: 'With grouped output, the max preview lines (number or "auto", default "auto")';
+        };
+        readonly noPrefix: {
+          readonly flags: ["-N", "--no-prefix"];
+          readonly description: "(DEPRECATED) Use --output-style=plain instead";
+          readonly deprecated: true;
+        };
+        readonly inline: {
+          readonly flags: ["-i", "--inline"];
+          readonly description: "Run the script as an inline command from the workspace directory";
+        };
+        readonly inlineName: {
+          readonly flags: ["-I", "--inline-name <name>"];
+          readonly description: "An optional name for the script when --inline is passed";
+        };
+        readonly shell: {
+          readonly flags: ["-s", "--shell <shell>"];
+          readonly values: ["bun", "system", "default"];
+          readonly description: "When using --inline, the shell to use to run the script";
+        };
+        readonly depOrder: {
+          readonly flags: ["-d", "--dep-order"];
+          readonly description: "Scripts for dependent workspaces run only after their dependencies";
+        };
+        readonly ignoreDepFailure: {
+          readonly flags: ["-f", "--ignore-dep-failure"];
+          readonly description: "In dependency order, continue running scripts even if a dependency fails";
+        };
+        readonly jsonOutfile: {
+          readonly flags: ["-j", "--json-outfile <file>"];
+          readonly description: "Output results in a JSON file";
+        };
+      };
+    }
+  | {
+      readonly command: "run-affected [script]";
+      readonly isGlobal: false;
+      readonly aliases: [];
+      readonly description: "Run a script across the workspaces affected by a set of changed files (git or file list)";
+      readonly options: {
+        readonly script: {
+          readonly flags: ["-S", "--script <script>"];
+          readonly description: "The script to run. (Alternative to positional argument)";
+        };
+        readonly base: {
+          readonly flags: ["-B", "--base <ref>"];
+          readonly description: "Git base ref to diff against (default is main if not configured). Cannot be used with --files";
+        };
+        readonly head: {
+          readonly flags: ["-H", "--head <ref>"];
+          readonly description: 'Git head ref to diff against (default "HEAD"). Cannot be used with --files';
+        };
+        readonly files: {
+          readonly flags: ["-F", "--files <files>"];
+          readonly description: "Changed files (paths/dirs/globs, '!' to exclude), separated by whitespace. Use backslashes to escape spaces if needed. Bypasses git, so cannot be used with --base or --head.";
+        };
+        readonly ignoreUntracked: {
+          readonly flags: ["--ignore-untracked"];
+          readonly description: "Exclude untracked files";
+        };
+        readonly ignoreUnstaged: {
+          readonly flags: ["--ignore-unstaged"];
+          readonly description: "Exclude unstaged files";
+        };
+        readonly ignoreStaged: {
+          readonly flags: ["--ignore-staged"];
+          readonly description: "Exclude staged files";
+        };
+        readonly ignoreUncommitted: {
+          readonly flags: ["--ignore-uncommitted"];
+          readonly description: "Exclude all uncommitted changes (staged, unstaged, untracked)";
+        };
+        readonly ignoreWorkspaceDeps: {
+          readonly flags: ["--ignore-workspace-deps"];
+          readonly description: "Ignore workspace dependencies derived from package.json files";
+        };
+        readonly ignoreExternalDeps: {
+          readonly flags: ["--ignore-external-deps"];
+          readonly description: "Ignore changes to external dependencies (e.g. npm packages) versions in bun.lock";
         };
         readonly parallel: {
           readonly flags: ["-P", "--parallel [max]"];
@@ -860,6 +1142,9 @@ export declare const getCliCommandConfig: (commandName: CliCommandName) =>
       };
     };
 export declare const getCliCommandNames: () => CliCommandName[];
+declare const LOG_LEVELS: readonly ["debug", "info", "warn", "error"];
+export type LogLevel = (typeof LOG_LEVELS)[number];
+export type LogLevelSetting = LogLevel | "silent";
 export interface CliGlobalOptions {
   logLevel: LogLevelSetting;
   cwd: string;
@@ -911,6 +1196,326 @@ export declare const getCliGlobalOptionConfig: (
       readonly param: "";
     };
 export declare const getCliGlobalOptionNames: () => CliGlobalOptionName[];
+/**
+ * A version delta for a single workspace's external dependency between
+ * two reference points (typically `baseRef` vs `headRef`).
+ *
+ * `baseVersion`/`headVersion` are `null` when the dep was absent at that
+ * side of the comparison (added or removed). When both are non-null and
+ * differ, the version was upgraded/downgraded.
+ *
+ * All four `package.json` dependency map sources participate. For
+ * `optionalDependencies` and `peerDependencies`, lockfile presence is the
+ * effective gate — if bun didn't resolve a version (e.g. an optional native
+ * binding skipped on this platform), no change is emitted.
+ */
+export type ExternalDependencyChange = {
+  /** The package name */
+  name: string;
+  /** Which `package.json` dependency map this dep was declared in */
+  source: ExternalDependencySource;
+  /** Version at the base point; `null` if absent */
+  baseVersion: string | null;
+  /** Version at the head point; `null` if absent */
+  headVersion: string | null;
+};
+export type AffectedDependencyEdgeSource = "input" | "package";
+export interface AffectedDependencyChainEntry {
+  workspaceName: string;
+  /**
+   * The kind of edge that led to this workspace from the previous chain entry.
+   * Undefined for the starting workspace at the head of the chain.
+   *
+   * "package" means the dependency is a true package.json-resolved dependency.
+   *
+   * "input" means the dependency comes from the workspace's workspace pattern inputs,
+   * from defaultInputs or a script's inputs.
+   */
+  edgeSource?: AffectedDependencyEdgeSource;
+}
+declare const GIT_AFFECTED_FILE_REASONS: readonly [
+  "diff",
+  "staged",
+  "unstaged",
+  "untracked",
+];
+export type GitAffectedFileReason = (typeof GIT_AFFECTED_FILE_REASONS)[number];
+export type AffectedChangedFile = {
+  /** The path to the file, relative to the project root */
+  projectFilePath: string;
+  /** The matched input for the file */
+  inputMatch: string;
+  /** Present when `diffSource` is "git": the reasons for the file being affected */
+  gitReasons?: GitAffectedFileReason[];
+};
+export type AffectedDependency = {
+  /** The name of the dependency */
+  dependencyName: string;
+  /** The chain of dependencies that led to the affected workspace */
+  chain: AffectedDependencyChainEntry[];
+};
+export type AffectedWorkspaceResult = {
+  workspace: Workspace;
+  inputs: WorkspaceInputsConfig;
+  isAffected: boolean;
+  affectedReasons: {
+    changedFiles: AffectedChangedFile[];
+    dependencies: AffectedDependency[];
+    /**
+     * External (non-workspace) dependency version deltas. In `git` mode the
+     * `baseVersion`/`headVersion` carry resolved versions from `bun.lock` at
+     * each ref. In `fileList` mode where `bun.lock` was listed as changed,
+     * both fields are `null` since no version comparison is possible.
+     */
+    externalDependencies: ExternalDependencyChange[];
+  };
+};
+/** The source for changed files */
+export type AffectedDiffSource = "git" | "fileList";
+export type AffectedWorkspacesMetadata = {
+  /** The source for changed files */
+  diffSource: AffectedDiffSource;
+  /** When `diffSource` is "git" */
+  git?: {
+    /** The base ref as provided (or the resolved default) */
+    baseRef: string;
+    /** The head ref as provided (or the resolved default) */
+    headRef: string;
+    /** The full SHA `baseRef` resolves to */
+    baseSha: string;
+    /** The full SHA `headRef` resolves to */
+    headSha: string;
+  };
+};
+export type AffectedWorkspacesResult = {
+  /** Metadata based on the parameters given */
+  metadata: AffectedWorkspacesMetadata;
+  /** The workspaces and their affected reasons */
+  workspaceResults: AffectedWorkspaceResult[];
+};
+export type BaseAffectedWorkspacesOptions<
+  AcceptsScript extends boolean = true,
+> = {
+  /** Skip cascading affected workspaces through `workspace:*` dependencies */
+  ignoreWorkspaceDependencies?: boolean;
+  /**
+   * Skip lockfile-based external dependency version tracking. In `git` mode
+   * this prevents reading `bun.lock` at base and head refs. In `fileList`
+   * mode this prevents `bun.lock` (when present in `changedFiles`) from
+   * triggering external-dep workspaces.
+   */
+  ignoreExternalDependencies?: boolean;
+} & (AcceptsScript extends true
+  ? {
+      script?: string;
+    }
+  : object);
+export type GitAffectedWorkspacesOptions<AcceptsScript extends boolean = true> =
+  BaseAffectedWorkspacesOptions<AcceptsScript> & {
+    /** Whether to use git to determine affected workspaces or a list of given files */
+    diffSource: "git";
+    diffOptions?: {
+      /**
+       * The base git ref to compare against.
+       *
+       * Default is "main" when not provided or
+       * when the default is not set by the
+       * root config or env var.
+       */
+      baseRef?: string;
+      /**
+       * The head git ref to compare against.
+       *
+       * Default is "HEAD" when not provided.
+       */
+      headRef?: string;
+      /** Exclude untracked files */
+      ignoreUntracked?: boolean;
+      /** Ignore staged files */
+      ignoreStaged?: boolean;
+      /** Ignore unstaged files */
+      ignoreUnstaged?: boolean;
+      /** Exclude any uncommitted files (ignores staged, unstaged, and untracked) */
+      ignoreUncommitted?: boolean;
+    };
+  };
+export type FileListAffectedWorkspacesOptions<
+  AcceptsScript extends boolean = true,
+> = BaseAffectedWorkspacesOptions<AcceptsScript> & {
+  /** Whether to use git or a list of given files to determine affected workspaces */
+  diffSource: "fileList";
+  /**
+   * File paths, directories, or glob patterns relative to the project root.
+   *
+   * - File paths are matched literally. Paths that don't exist on disk
+   *   pass through as-is.
+   * - Directories are walked recursively into a flat file list. The
+   *   `node_modules` and `.git` directories are skipped during the walk.
+   * - Globs are expanded via `bun.Glob` against the project root and
+   *   only match files that currently exist.
+   * - Prefix with `!` to exclude. Exclusions are expanded the same way
+   *   and removed from the include set.
+   */
+  changedFiles: string[];
+};
+export type DetermineAffectedWorkspacesOptions<
+  AcceptScript extends boolean = true,
+> =
+  | GitAffectedWorkspacesOptions<AcceptScript>
+  | FileListAffectedWorkspacesOptions<AcceptScript>;
+/** Arguments for {@link createFileSystemProject} */
+export type CreateFileSystemProjectOptions = {
+  /** The directory containing the root package.json. Often the same root as a git repository. Relative to process.cwd(). The default is process.cwd(). */
+  rootDirectory?: string;
+  /**
+   * The name of the project.
+   *
+   * By default will use the root package.json name
+   */
+  name?: string;
+  /** Whether to include the root workspace as a normal workspace. This overrides any config or env var settings. */
+  includeRootWorkspace?: boolean;
+};
+export type InlineScriptOptions = {
+  /** A name to act as a label for the inline script */
+  scriptName?: string;
+  /** Whether to use the system shell or Bun shell */
+  shell?: ShellOption;
+};
+/** Arguments for `FileSystemProject.runWorkspaceScript` */
+export type RunWorkspaceScriptOptions = {
+  /** The name of the workspace to run the script in */
+  workspaceNameOrAlias: string;
+  /** The name of the script to run, or an inline command when `inline` is true */
+  script: string;
+  /** Whether to run the script as an inline command */
+  inline?: boolean | InlineScriptOptions;
+  /** The arguments to append to the script command. If passed as a string, the argv will be parsed POSIX-style */
+  args?: string | string[];
+  /** Set to `true` to ignore all output from the script. This saves memory when you don't need script output. */
+  ignoreOutput?: boolean;
+};
+/** Metadata associated with a workspace script */
+export type RunWorkspaceScriptMetadata = {
+  /** The workspace that the script was run in */
+  workspace: Workspace;
+};
+export type RunWorkspaceScriptExit = Simplify<
+  RunScriptExit<RunWorkspaceScriptMetadata>
+>;
+export type RunWorkspaceScriptProcessOutput = MultiProcessOutput<
+  RunWorkspaceScriptMetadata & {
+    streamName: OutputStreamName;
+  }
+>;
+/** Result of `FileSystemProject.runWorkspaceScript` */
+export type RunWorkspaceScriptResult = {
+  /** Use to get the output of the script */
+  output: RunWorkspaceScriptProcessOutput;
+  /** The exit result of the script */
+  exit: Promise<RunWorkspaceScriptExit>;
+};
+export type ParallelOption = boolean | RunScriptsParallelOptions;
+export type ScriptEventMetadata = {
+  /** The workspace that the script event occurred in */
+  workspace: Workspace;
+  /** The exit result of the script */
+  exitResult: RunScriptExit<RunWorkspaceScriptMetadata> | null;
+};
+export type OnScriptEventCallback = (
+  /** The event that occurred */
+  event: ScriptEventName,
+  /** The metadata for the script event */
+  metadata: ScriptEventMetadata,
+) => unknown;
+/** Arguments for `FileSystemProject.runScriptAcrossWorkspaces` */
+export type RunScriptAcrossWorkspacesOptions = {
+  /**
+   * Workspace names, aliases, or patterns including a wildcard.
+   *
+   * When not provided, all workspaces that the script can be ran in will be used.
+   */
+  workspacePatterns?: string[];
+  /** The name of the script to run, or an inline command when `inline` is true */
+  script: string;
+  /** Whether to run the script as an inline command */
+  inline?: boolean | InlineScriptOptions;
+  /** The arguments to append to the script command. If passed as a string, the argv will be parsed POSIX-style */
+  args?: string | string[];
+  /** Whether to run the scripts in parallel (default: `true`). Pass `false` to run in series. */
+  parallel?: ParallelOption;
+  /** When `true`, run scripts so that dependent workspaces run only after their dependencies */
+  dependencyOrder?: boolean;
+  /** When `true`, continue running scripts even if a dependency fails (Only relevant when `dependencyOrder` is `true`) */
+  ignoreDependencyFailure?: boolean;
+  /** Set to `true` to ignore all output from the scripts. This saves memory when you don't need script output. */
+  ignoreOutput?: boolean;
+  /** Callback to invoke when a script event occurs (start, skip, exit) */
+  onScriptEvent?: OnScriptEventCallback;
+};
+export type RunScriptAcrossWorkspacesSummary = Simplify<
+  RunScriptsSummary<RunWorkspaceScriptMetadata>
+>;
+export type RunScriptAcrossWorkspacesOutput = MultiProcessOutput<
+  RunWorkspaceScriptMetadata & {
+    streamName: OutputStreamName;
+  }
+>;
+/** Result of `FileSystemProject.runScriptAcrossWorkspaces` */
+export type RunScriptAcrossWorkspacesResult = {
+  /** Use to get the output of the scripts */
+  output: RunScriptAcrossWorkspacesOutput;
+  /** The summary of the script run with exit details for each workspace */
+  summary: Promise<RunScriptAcrossWorkspacesSummary>;
+  /** The workspaces targeted */
+  workspaces: Workspace[];
+};
+export type RunAffectedWorkspaceScriptOptions = {
+  /**
+   * Options for resolving the affected workspaces. The `script` field is
+   * intentionally omitted — it is derived from `scriptOptions` (the inline
+   * script name when running inline, the script name otherwise) so that
+   * inputs resolution always tracks the script being run.
+   */
+  affectedOptions: DetermineAffectedWorkspacesOptions<false>;
+  scriptOptions: Omit<RunScriptAcrossWorkspacesOptions, "workspacePatterns">;
+};
+declare class _FileSystemProject extends ProjectBase implements Project {
+  #private;
+  readonly rootDirectory: string;
+  readonly workspaces: Workspace[];
+  readonly name: string;
+  readonly sourceType = "fileSystem";
+  readonly config: ProjectConfig;
+  readonly rootWorkspace: Workspace;
+  constructor(options: CreateFileSystemProjectOptions);
+  runWorkspaceScript(
+    options: RunWorkspaceScriptOptions,
+  ): RunWorkspaceScriptResult;
+  runScriptAcrossWorkspaces(
+    options: RunScriptAcrossWorkspacesOptions,
+  ): RunScriptAcrossWorkspacesResult;
+  /**
+   * Determine the affected workspaces based on the given options.
+   *
+   * Returns a summary of all workspaces, whether they are affected or not,
+   * and the reasons why they are affected.
+   */
+  determineAffectedWorkspaces(
+    options: DetermineAffectedWorkspacesOptions,
+  ): Promise<AffectedWorkspacesResult>;
+  /**
+   * Run the script across the affected workspaces.
+   *
+   * Similar to {@link runScriptAcrossWorkspaces}, but only runs the script across the affected workspaces.
+   */
+  runAffectedWorkspaceScript({
+    affectedOptions,
+    scriptOptions,
+  }: RunAffectedWorkspaceScriptOptions): Promise<RunScriptAcrossWorkspacesResult>;
+}
+/** An implementation of {@link Project} that is created from a root directory in the file system. */
+export type FileSystemProject = Simplify<_FileSystemProject>;
 /** @todo DRY use of output text in cases such as having no workspaces/scripts */
 export type GlobalCommandContext = {
   program: Command;
@@ -1028,6 +1633,9 @@ export declare const mcpServer: (
 export declare const runScript: (
   context: ProjectCommandContext,
 ) => import("commander").Command;
+export declare const runAffected: (
+  context: ProjectCommandContext,
+) => import("commander").Command;
 export type RenderPlainOutputOptions = {
   stripDisruptiveControls?: boolean;
   prefix?: boolean;
@@ -1068,6 +1676,13 @@ export declare const initializeWithGlobalOptions: (
     runScriptAcrossWorkspaces(
       options: RunScriptAcrossWorkspacesOptions,
     ): RunScriptAcrossWorkspacesResult;
+    determineAffectedWorkspaces(
+      options: DetermineAffectedWorkspacesOptions,
+    ): Promise<AffectedWorkspacesResult>;
+    runAffectedWorkspaceScript({
+      affectedOptions,
+      scriptOptions,
+    }: RunAffectedWorkspaceScriptOptions): Promise<RunScriptAcrossWorkspacesResult>;
     listWorkspacesWithScript(scriptName: string): Workspace[];
     mapScriptsToWorkspaces(): Record<string, WorkspaceScriptMetadata>;
     mapTagsToWorkspaces(): Record<string, Workspace[]>;