Proposal: Officially migrate build system to Astral UV for reproducible installs

[RAliane]

Draft GitHub Issue — To be posted at user's discretion

Repository: 0x4m4/hexstrike-ai
Title: Proposal: Officially migrate build system to Astral UV for reproducible installs
Labels: enhancement, build-system, good-first-issue

---

Summary

The current README recommends a standard python3 -m venv + pip3 install -r requirements.txt workflow. In practice this produces non-deterministic environments, dependency-resolution hangs, and runtime ABI crashes on fresh machines.

Problem Observed

While setting up HexStrike AI v6.0 for an OSINT engagement, the prescribed pip workflow failed to yield a working server. Key issues:

1. Dependency Hell — requirements.txt uses wide ranges (e.g. flask>=2.3.0,<4.0.0) and includes heavy binary-analysis packages (angr, pwntools, mitmproxy). Pip's resolver either backtracked for minutes or installed incompatible versions of bcrypt, cryptography, and requests.
2. Python Version Ambiguity — README does not specify a minimum Python version. The system default (3.12) was used, yet some transitive C-extensions compiled against different ABI headers and segfaulted on import.
3. No Lockfile — Without a lockfile, every fresh install is a gamble. This is a blocker for CI and team onboarding.

Solution Proposed

Adopt Astral UV as the official build tool:

• Fast: Rust-based resolver installs the full 144-package stack (including compiled wheels like capstone, unicorn, z3-solver) in ~30 seconds.
• Deterministic: Bit-for-bit reproducible installs via wheel cache.
• Python-version pinning: UV can fetch and lock an explicit CPython version (e.g. --python 3.12) independent of the host, eliminating ABI/segfault issues.

Immediate Workaround (Documented)

The following was verified to work on Ubuntu 24.04 / Podman host:

# Install UV if not present
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create venv with explicit Python 3.12
uv venv --python 3.12 hexstrike-env
source hexstrike-env/bin/activate

# Install dependencies
uv pip install -r requirements.txt

# Start server
python3 hexstrike_server.py --port 8888

Long-term Migration Checklist

• Add pyproject.toml with project metadata and dependency groups
• Generate and commit uv.lock
• Update README install instructions
• Update CI (GitHub Actions) to use uv run
• Add CACHEDIR.TAG / .gitignore guidance for UV cache

References

• ADR-0001 (local): docs/adr/0001-move-to-uv-package-manager.md
• UV docs: https://docs.astral.sh/uv/