Anthony Shew

This commit delivers a **bug fix** for the **`turbo prune` command**, specifically addressing its interaction with **pnpm monorepos** configured for **per-workspace lockfiles** (`shared-workspace-lockfile=false`). Previously, `prune` would incorrectly merge all workspace lockfiles into a single shared lockfile and modify `.npmrc`, causing subsequent `pnpm install` operations in the pruned output to fail. The `prune` command now correctly detects this configuration via `.npmrc` and preserves individual workspace lockfiles, copies the root lockfile verbatim, and leaves the `.npmrc` file untouched. This ensures that pruned repositories remain functional and consistent with their original lockfile strategy, significantly improving the reliability of the **pruning functionality** for `pnpm` users.

This **bug fix** addresses an issue in **npm lockfile pruning** where the `rehoist_packages()` function incorrectly promoted workspace-nested packages to the root `node_modules/` when `install-strategy=shallow` was configured. The `crates/turborepo-lockfiles/src/npm.rs` module now ensures that rehoisting only occurs if the original lockfile already contained a hoisted entry, thereby preserving the intended shallow installation strategy. This resolves `npm ci` failures and "Cannot find module" errors, ensuring lockfile consistency for projects utilizing **npm workspaces** with this specific installation strategy. A new regression test and e2e fixture were added to prevent future regressions.

This commit delivers a crucial **bug fix** and **refactoring** to the **Turborepo engine's graph pruning logic**, specifically within the `retain_affected_tasks` and `create_engine_for_subgraph` functions in `crates/turborepo-engine/src/lib.rs`. It ensures that when pruning the task graph for `--affected` or watch modes, **transitive dependencies** are now correctly included alongside transitive dependents, preventing upstream tasks from being erroneously removed. This resolves an issue where builds could fail due to missing artifacts from unexecuted upstream tasks on cold caches or first runs. The change also extracts shared graph traversal helpers and includes comprehensive new unit and integration tests, along with updated documentation across `turborepo-lib` and `turborepo`.

This commit delivers a **bug fix** for `turbo prune`'s interaction with **pnpm lockfiles**, specifically addressing an issue where `pnpm install --frozen-lockfile` would fail after pruning. The problem arose when pnpm workspace packages with zero dependencies had their importer entries omitted from the lockfile, causing subsequent `pnpm install` commands to fail. This change modifies the `PnpmLockfile::subgraph` function within `crates/turborepo-lockfiles/src/pnpm/data.rs` to **backfill these missing pnpm workspace importer entries**, ensuring all necessary entries are present. This significantly improves the reliability of `turbo prune` for **pnpm monorepos** by guaranteeing successful `pnpm install` operations post-pruning, even for dependency-free packages.

This commit significantly **improves the documentation** for **Turborepo's code generation features** by explicitly detailing the `turbo` object and its injected variables, `turbo.paths` and `turbo.configs`. It adds a new guide-level section to the `Generating code` documentation (`/docs/guides/generating-code.mdx`), illustrating their usage in Handlebars templates and custom actions. Furthermore, a comprehensive reference table is included in the `@turbo/gen` page (`/docs/reference/turbo-gen.mdx`), providing clear guidance on these previously undocumented generator variables. This **documentation enhancement** makes it easier for developers to understand and utilize dynamic aspects of Turborepo generators, moving beyond source code discovery.

This commit delivers a **bug fix** that resolves an issue where **interruptible persistent tasks** in **`watch` mode** would not restart on file changes. The problem stemmed from a `TaskTracker` for detached, fire-and-forget persistent tasks blocking the main `ExecutionTracker`, which prevented the `watch` loop from processing subsequent file-change events. The **fix** introduces a **no-op `TaskTracker`** specifically for these persistent tasks, allowing the `ExecutionTracker` to complete and unblocking the `watch` loop. This ensures that **persistent tasks correctly respond to file modifications**, and additional **debug logging** has been added to `crates/turborepo-lib/src/run/watch.rs` for improved diagnosability of future watch-mode issues.

This commit **reverts** a prior **bug fix attempt** aimed at preventing macOS Gatekeeper CPU spikes by modifying PTY spawning. It undoes the custom Unix PTY spawning logic within `crates/turborepo-process/src/child.rs`, specifically removing the `spawn_pty_child_unix` helper and restoring `spawn_pty` to use `portable-pty`'s default `spawn_command`. This **revert** acknowledges that the true resolution for the Gatekeeper issue is proper macOS binary signing, impacting the **process spawning and PTY handling** subsystem.

fix: Resolve correct nested bun lockfile versions during prune (#12506)

This commit **adds comprehensive documentation** for the recently introduced **local cache eviction options**, `cacheMaxAge` and `cacheMaxSize`. It updates `configuration.mdx` with details on these global options and their future flag mappings, and `system-environment-variables.mdx` to document `TURBO_CACHE_MAX_AGE` and `TURBO_CACHE_MAX_SIZE`. The `options-overview.mdx` table is updated, and `caching.mdx` now includes an explanation of the two-phase (TTL then LRU) eviction algorithm. This **documentation update** ensures users can effectively configure and understand the behavior of local cache eviction.

This commit **fixes a reliability issue** in the **`update-examples-on-release` GitHub workflow**, preventing failures during the push step. Previously, the workflow would fail when attempting to push to the `post-release-bump-examples` branch if it already existed from a prior run. To resolve this, the workflow now executes a `git pull --rebase` command before pushing, ensuring existing remote history is properly incorporated. Furthermore, a 3-attempt retry loop has been added to the push operation within `.github/workflows/update-examples-on-release.yml` to handle transient network or repository issues, significantly improving the robustness and reliability of the automated example update process.

This commit introduces a **new capability** to **Turborepo's local cache management** by implementing automatic eviction based on age and size. Users can now configure `cacheMaxAge` (time-to-live) and `cacheMaxSize` (least recently used) in `turbo.json` or via `TURBO_CACHE_MAX_AGE` and `TURBO_CACHE_MAX_SIZE` environment variables to prevent unbounded cache growth. The eviction process runs efficiently in a background thread at `turbo run` startup, ensuring improved cache hygiene without impacting task scheduling. This feature provides greater control over local storage usage and is opt-in, requiring explicit configuration to take effect.

This commit introduces a **new capability** to the `turbo-codemod`'s migration process, enabling it to correctly handle **package manager catalogs** like those used by pnpm and Yarn Berry. Previously, the codemod would inadvertently break `catalog:` references by overwriting them with literal version strings; now, it **detects these catalog protocols**, directly updates the version within the respective catalog file (e.g., `pnpm-workspace.yaml`, `.yarnrc.yml`), and then performs a generic `install` to sync the lockfile. This **bug fix** prevents unintended modifications to monorepo configurations and includes an improvement to `getLatestVersion` to accurately resolve dist-tags like `latest` to concrete versions, ensuring a smoother and more reliable upgrade experience for users leveraging advanced package management features.

This commit introduces a **bug fix** to the **release workflow** defined in `.github/workflows/turborepo-release.yml`. Previously, the automated generation of **release notes** for minor and major versions would incorrectly use the latest patch release as the starting point, leading to incomplete change logs. This update modifies the "Get previous tag" step to correctly identify the preceding minor or major tag (`vX.Y.0`), ensuring that **all changes from intermediate patch releases are accurately included**. This guarantees **comprehensive and correct release notes** for all future minor and major releases.

This commit primarily focuses on **documentation updates** to announce the **Turborepo 2.9 release**. It introduces a new blog post detailing the release's features and performance improvements, alongside comprehensive updates across various documentation sections. The **configuration reference** is updated to include new **future flags** such as `filterUsingTasks` and `globalConfiguration`, and the `turbo query` command's `--schema` flag is now documented. Furthermore, **core concepts**, the deprecated `turbo scan` command, and the **support policy** are updated to reflect the latest changes and API deprecations, ensuring users have up-to-date information on new capabilities and breaking changes.

This commit **fixes** an issue preventing **workspace packages** located within **symlinked directories** from being discovered by `turborepo` when using `**` glob patterns. It introduces a `follow_links` setting to the **`turborepo-globwalk`** crate's `globwalk::Settings` and enables it specifically within `WorkspaceGlobs::get_package_jsons` for **workspace package discovery**. This **bug fix** ensures that `turborepo` can correctly identify all packages, even those behind symlinks, enhancing flexibility for complex monorepo structures. Eight new regression tests were added to validate symlink traversal and cycle detection.

This commit delivers a **bug fix** to the **cache restoration process** within `turborepo-cache`, addressing an issue where pre-existing symlinks could cause cached files to be restored to incorrect locations. Specifically, the `CachedDirTree` now tracks symlinks created by the archive and, during `safe_mkdir_all`, detects and replaces any *other* pre-existing symlinks with actual directories. This prevents files from "leaking" through symlinks (e.g., `dist/runtime` being a symlink to `src/runtime`), ensuring **correct file placement** and improving the **robustness of cache restores**.

This commit introduces a **performance optimization** to the **`turborepo-cache`** system by **skipping the writing of unchanged files** during slow-path cache restoration. Previously, when the fast-path validation failed, the slow path would rewrite every file from the tar archive, leading to excessive I/O and filesystem notifications. Now, the `FSCache::fetch` method intelligently checks existing files against the previous manifest, preventing unnecessary disk writes and **reducing rebuilds in dev servers** like Next.js. This **bug fix** significantly improves the efficiency of cache restores when only a few output files have changed, by modifying `restore_regular` to return whether a file was written or skipped.

This commit introduces a **new capability** by allowing the `experimentalCI` boolean field within `turbo.json` task configurations. It **updates the `turborepo-turbo-json` crate's parsing logic** to accept this field in `RawTaskDefinition` without validation errors, preventing `turbo.json` from being rejected. While Turborepo itself does not process or act upon this value, this change enables **external CI systems** to read and utilize this configuration directly from `turbo.json`. The field is intentionally undocumented and excluded from schema and types, ensuring it serves as an external-facing flag without impacting Turborepo's core functionality.

This commit **fixes** an issue in the **`@turbo/codemod` package** where upgrade commands were incorrectly generated for **Yarn 2+ environments**. The `createNotifyUpdate` function now correctly suggests local installs using `yarn dlx` for Yarn 2+ versions, while `getGlobalUpgradeCommand` is updated to return `undefined` for these versions, ensuring `getTurboUpgradeCommand` falls back to a local installation command. This **improves compatibility** and provides **correct upgrade instructions** for users leveraging **Yarn 2+ and Yarn 4.x**, preventing potential installation failures or confusion. New test cases have been added to validate the correct behavior for Yarn 4.x local installs.

This commit **fixes** a bug preventing the **execution summary** (tasks, cache, time) from displaying after the **Terminal User Interface (TUI)** exited. The issue stemmed from the TUI receiving an `Event::Stop` signal prematurely, causing it to terminate before summary log events could be processed. The **fix** involves removing the early `Event::Stop` from the task graph visitor (`crates/turborepo-lib/src/task_graph/visitor/mod.rs`) and introducing a new `persist_summary()` function in the **TUI application** (`crates/turborepo-ui/src/tui/app.rs`). This ensures `Subsystem::Summary` log events are explicitly replayed to stdout during TUI cleanup, guaranteeing users consistently see the **execution summary** after `turbo run` commands.