Silent pre-requisite failures: missing uv causes cryptic downstream errors instead of actionable guidance

[smakubi]

Summary

The pre-requisite checker reports success even when required tools are missing or misconfigured, leading to confusing downstream failures that are hard to diagnose for users.

Observed Behavior

When a user has pip3 installed but not uv, the pre-requisite check passes (or at least does not block/warn). Installation proceeds, then fails with a cryptic error deep in the setup process:

ERROR: File "setup.py" or "setup.cfg" not found.
Directory cannot be installed in editable mode:
/Users/briannicosia/.ai-dev-kit/repo/databricks-tools-core
(A "pyproject.toml" file was found, but editable mode currently requires
a setuptools-based build.)

This error is misleading — the root cause is not actually a missing setup.py, but rather that the editable install is being attempted with pip/pip3 instead of uv, and pip's editable install mechanism does not support pyproject.toml-only packages without a setuptools backend configured.

Root Cause Analysis

• databricks-tools-core (and likely other packages in the repo) uses a pyproject.toml-only build system — the modern standard.
• uv handles editable installs of pyproject.toml-only packages natively and correctly.
• Older pip versions (and pip3 without the right setuptools/pip version) require a setup.py or setup.cfg for editable installs (pip install -e .), hence the error.
• The pre-requisite checker does not verify that uv is installed, or falls back silently to pip3 without warning the user.

Expected Behavior

The pre-requisite checker should:

1. Explicitly check for uv — verify it is installed and on $PATH (e.g. which uv or uv --version).
2. Hard-fail with a clear, actionable error if uv is missing — do not proceed with installation.
3. Not silently fall back to pip/pip3 — if it does fall back, warn loudly and explain why it will likely fail.
4. Provide the user with the exact install command to fix the issue, e.g.:

   uv is required but was not found on your PATH.
   Install it with: curl -LsSf https://astral.sh/uv/install.sh | sh
   Then re-run this setup script.
   

Steps to Reproduce

1. Have a machine with Python and pip3 installed but without uv.
2. Run the AI Dev Kit setup/install process.
3. Observe that pre-requisite check passes (no warning about missing uv).
4. Installation proceeds and fails with the setup.py not found error.

Actual Fix

Installing uv resolved the issue immediately:

curl -LsSf https://astral.sh/uv/install.sh | sh

After installing uv, the same setup completed successfully — confirming uv is a hard dependency that must be enforced at the pre-requisite stage.

Additional Context

• This is a silent failure — the user gets no actionable guidance and is left to diagnose a setuptools error that has nothing to do with the actual problem.
• Users with Python experience may be confused because the error message points at the package structure (setup.py missing) rather than the tool (uv missing), sending them down the wrong debugging path.
• This is particularly likely to affect users coming from traditional Python workflows who have pip3 but have not yet adopted uv.

Suggested Fix

In the pre-requisite checking logic:

# Check for uv
if ! command -v uv &> /dev/null; then
  echo "❌ ERROR: 'uv' is required but not found on your PATH."
  echo "   Install it with: curl -LsSf https://astral.sh/uv/install.sh | sh"
  echo "   Then re-run this script."
  exit 1
else
  echo "✅ uv found: $(uv --version)"
fi

And ensure the installer never silently falls back to pip or pip3 for editable installs of packages in this monorepo.

Environment

• macOS (darwin)
• Python 3.x with pip3 installed, uv not installed
• AI Dev Kit setup script