Elvis Pranskevichus

This commit **enhances the CLI build process** by introducing **namespacing for diagnostics keys** and **validating package manifests**. Specifically, it prefixes diagnostics file keys with the builder name and service workspace path to prevent collisions in **multi-service or multi-builder builds**, while single-project builds remain unaffected. Additionally, it adds a new `packageManifestSchema` to `packages/build-utils` for **validating builder-produced `package-manifest.json` files** and aggregates these into a single `project-manifest.json`. This work is a **build tooling improvement** that ensures more robust and organized diagnostics output, particularly for complex build configurations.

This commit **fixes a bug** where Python dependencies guarded by environment markers that exclude the target platform were erroneously checked for wheel compatibility and force-bundled. It introduces a new **WASM binding `evaluateMarker`** in the **`python-analysis` module** to accurately evaluate **PEP 508 environment markers**. The **`python` dependency externalizer** now leverages this to identify packages truly **reachable on the target platform** before performing **wheel compatibility checks**, preventing incorrect bundling. This enhances the precision of **Python dependency resolution** by ensuring only relevant packages are processed for a given environment.

This commit introduces a **new capability** to the **Python builder** by adding a `diagnostics` callback, which generates a `package-manifest.json` file. This manifest provides **structured project metadata**, including the runtime, resolved Python version, and a comprehensive dependency inventory. The `generateProjectManifest` function, leveraging new PEP 508 parsing utilities within `packages/python-analysis`, collects and classifies dependencies from `pyproject.toml` and resolves their versions and sources from `uv.lock`. This **diagnostic feature** enhances introspection into Python projects by providing a detailed, machine-readable manifest, without altering existing build processes. The manifest is only produced when a `uv.lock` file is present, ensuring relevant dependency resolution data is available.

This commit **fixes** a critical build failure in the **Python runtime's dependency externalization** process. Previously, projects would fail if `uv sync --no-build` encountered packages without pre-built wheels compatible with the Lambda platform. Now, the **dependency externalizer** intelligently identifies these problematic packages using new **wheel compatibility checks** (implemented in `python-analysis` and leveraging `uv-platform-tags`) and **force-bundles** them into the Lambda package instead of failing the build. This **enhances the robustness** of Python deployments by ensuring projects with such dependencies can still be built and deployed successfully. The `python` package's build process now includes platform detection via `detectPlatform` to inform these compatibility checks.

This commit introduces a significant **refactoring** within the **`python-analysis` package**, specifically for parsing `requirements.txt` files. It replaces the existing JavaScript-based `pip-requirements-js` parser with a new **WASM-based implementation powered by `uv`**, effectively **removing an external npm dependency**. This change enhances the reliability and potential performance of Python dependency analysis by leveraging Rust-compiled `uv` functionality, with expanded test coverage in `requirements-txt-parser.test.ts` to validate the new logic. The core parsing logic is updated in `packages/python-analysis/src/manifest/requirements-txt-parser.ts`, integrating new WASM interaction functions.

This commit implements a **significant performance optimization** for the **`python-analysis` WASM binary** by **refactoring** IDNA and Unicode normalization operations. It moves these computationally intensive tasks, including domain-to-ASCII/Unicode conversions and various Unicode normalization forms, from the WASM component to the Node.js host. This is achieved by introducing new stub crates (`idna-stub`, `unicode-normalization-stub`, `unicode-names2-stub`) that delegate to the host via an extended `host-utils` WIT interface, leveraging native Node.js `URL` and `String.prototype.normalize` functions. The primary impact is a **40% reduction in the WASM binary size** (from 2.73 MB to 1.64 MB) by eliminating large embedded ICU/Unicode lookup tables. A custom `wasm-test-runner.mjs` was also added to facilitate testing of these host-dependent WASM components.

This commit introduces **requirements.txt parsing** functionality to the `python-analysis` package, enabling it to convert `requirements.txt` files into structured data including PEP 508 specifiers and VCS URLs. This **new capability** is implemented by integrating the `uv-requirements-txt` crate, which required extensive **refactoring** of its dependencies into WASM-compatible stub crates (e.g., `uv-client-stub`, `uv-fs-stub`) to avoid heavy async runtimes. A new **host-bridge** (`host-utils.ts`) facilitates file I/O for resolving includes within the WASM module by delegating to the host. The `parse-requirements-txt` function is exposed via a WIT export, significantly enhancing the **Python dependency analysis** capabilities within the WASM environment.

This commit **enhances the Python package publishing workflow** by replacing the fragile `git diff` version comparison with a direct query to PyPI. Previously, the system could incorrectly skip publishing a package if a prior attempt failed, leading to release breakage. The **`python/publish.mjs` script** now leverages `isPublishedOnPyPI` to determine if a package version is already live on PyPI, ensuring publishing decisions are based on the **actual PyPI state**. This **critical bug fix and improvement** makes the release pipeline significantly more robust and reliable.

This commit **refactors** the **Python version resolution** logic, centralizing it from ad-hoc parsing within the `packages/python` builder into structured APIs in the **`@vercel/python-analysis`** package. It introduces new capabilities within `python-analysis`, such as `selectPythonVersion` for two-pass version selection, improved manifest parsing including `Pipfile.lock`, and better handling of version constraints. Consequently, the **`packages/python`** module is updated to consume these new, robust APIs for detecting, installing, and synchronizing Python dependencies during the build process. This **enhances the maintainability and reliability** of the Python build system by providing a single source of truth for version logic, ensuring consistent behavior across different build stages. The change is a **low-risk refactoring** with extensive test coverage, aiming for no functional alteration to the user experience.

This commit **enhances error reporting** within the **Python runtime** by ensuring that **fatal initialization errors** are no longer silently lost. Previously, these critical errors were only written to stderr; now, the runtime sends an **`unrecoverable-error` IPC message** before exiting, allowing the **Functions Runtime (SFR)** to properly detect and handle them. This involved **refactoring** the `_fatal()` function, introducing a new `_fatal_exc()` helper for errors with tracebacks, and replacing all `_stderr(); exit(1)` patterns with the unified `_fatal()` approach in `vc_init.py`. The change significantly improves the **observability and reliability** of Python function deployments by providing a robust mechanism for the **Functions Runtime** to receive crucial error signals during startup.

This commit introduces **support for the `litellm` proxy** within the **Python runtime**, enabling seamless deployment of applications utilizing `litellm`. It implements a **new `litellmQuirk`** that integrates into the existing **quirks system**, specifically informing the `prisma` quirk about the location of `litellm`'s persistence schema. This **new capability** allows `litellm` proxy to function out-of-the-box with minimal configuration, primarily by detecting `litellm_config.yaml`. The change includes comprehensive test fixtures and unit tests to validate the quirk's functionality and schema path propagation.

This commit introduces a **new "quirks" system** to the **Python build process** to enable full support for `prisma-client-py` on Vercel. This **infrastructure change** addresses `prisma-client-py`'s limitations with platform-specific binaries and `openssl` by executing post-install fix-ups. The dedicated `prisma` quirk downloads the correct query engine, bundles an `openssl` shim, and optionally runs `prisma generate`, while also modifying the runtime `PATH` via `VERCEL_RUNTIME_ENV_PATH_PREPEND`. This **new capability** allows developers to seamlessly deploy applications utilizing `prisma-client-py` on Vercel.

This commit **fixes a critical bug** in the **Python runtime's legacy ASGI invocation path** (`vc_init.py`) where lifespan events were not properly sent, causing frameworks like FastAPI to fail with `ClientNotConnectedError` when relying on startup hooks (e.g., `prisma.connect()`). It **implements full ASGI lifespan protocol support** by introducing a **persistent `asyncio` event loop** shared between lifespan tasks and per-request `ASGICycle` invocations, complete with an `atexit` handler for clean shutdown. This **enhancement** ensures proper startup and shutdown event handling, resolving reliability issues for applications deployed in the legacy ASGI mode. The fix was identified during testing with `vd invoke` and includes new test fixtures to verify correct lifespan behavior.

This commit **introduces new documentation** within the `python/` directory, specifically adding `AGENTS.md` and `CLAUDE.md`. It provides comprehensive **development guidelines** for **Python tooling, code style, and git commit practices**, with `CLAUDE.md` referencing the primary `AGENTS.md` document. This is a **documentation addition** and **maintenance** task, involving no functional code changes, intended to standardize development practices for Python components and improve developer consistency.

This commit **improves type checking compliance** across the **Python runtime** by addressing warnings and errors from `mypy` and `pyright`. It introduces extensive **type annotations** to functions and methods within `vercel_runtime/vc_init.py` and refines test files to re-enable and add type annotations for type checking tests. Additionally, the `pyproject.toml` configuration was updated to adjust type checker settings, ensuring stricter static analysis. This **maintenance** work enhances code robustness and maintainability without altering any runtime logic or security controls.

This commit **re-adds** the `environment: release` configuration to the **GitHub Actions release workflow**, rectifying an inadvertent removal that impacted the **PyPI trusted publishing** process. This **critical infrastructure fix** restores a key component of the **release pipeline**, ensuring the secure and automated deployment of packages to PyPI. The change is a **high-risk deployment correction** essential for maintaining the integrity of the publishing mechanism.

This commit performs **maintenance** on the **Python runtime** by applying extensive **linting and formatting** changes to `python/vercel-runtime/src/vercel_runtime/vc_init.py` using `ruff`. It includes import reordering, quote style normalization, and line wrapping, alongside minor variable name adjustments, all without introducing any functional changes. The `pyproject.toml` configuration for `ruff` is also updated to globally ignore pydocstyle and re-enable previously skipped lint/format tests, improving overall code consistency and adherence to style guidelines. This **refactoring** ensures the codebase is cleaner and more maintainable, with no impact on runtime behavior.

This commit significantly enhances the **Python runtime**'s development infrastructure by introducing a comprehensive suite of **tests**, linters, and type checkers. It establishes a new **GitHub Actions workflow** (`.github/workflows/test-python-runtime.yml`) to automate these checks, configuring tools like `pytest`, `mypy`, `ruff`, and `basedpyright` within `pyproject.toml`. Extensive integration tests (`python/vercel-runtime/tests/test_runtime.py`) cover existing HTTP, WSGI, and ASGI handler implementations, supported by various fixtures and a mock IPC server. This **maintenance** and **infrastructure improvement** work ensures the reliability and maintainability of the **Python runtime** by enforcing code quality and verifying functional correctness across its core components.

This commit introduces a **new capability** to the **`python-analysis` package** by implementing an MVP for parsing installed Python distribution metadata, similar to `importlib.metadata`. It leverages new Rust crates like `uv-pypi-types` and `csv` to accurately parse `METADATA`, `RECORD`, and `direct_url.json` files from `.dist-info` directories. This new infrastructure is then used to **refactor** the `mirrorSitePackagesIntoVendor` and `mirrorPrivatePackagesIntoVendor` functions within the **`python` package**, enabling more precise and robust file mirroring based on the contents of `RECORD` files. The change significantly improves the reliability and accuracy of Python dependency management by providing detailed information about installed packages.

This commit **refactors** and **enhances** the **CI/CD release workflow** to correctly integrate the **Python runtime package publication**. It resolves a critical issue where e2e tests failed because the Python builder couldn't find the `vercel-runtime` package on PyPI before its official release. To address this, the system now builds and uploads Python wheel artifacts to Vercel for pre-release e2e testing, using the `VERCEL_RUNTIME_PYTHON` environment variable. Furthermore, the PyPI publication step is now executed within the `ci:publish` script, ensuring it completes *before* the main `npm publish` to prevent broken builds. This significantly improves the reliability of the **Python runtime release process** and **e2e testing infrastructure**.