feat: support lean Android/Termux bootstrap with optional native deps

[kvandre12-commits]

Summary

This PR makes Code Puppy installable on Android/Termux by keeping native-heavy optional capabilities out of the base dependency path and adding a lean bootstrap flow for phones.

Key changes:

• Move Playwright behind the optional browser extra and guard browser imports so the CLI still boots without it.
• Move the PyPI ripgrep bundle behind the optional search extra; Code Puppy already uses the system rg binary when available.
• Keep image/token-counting native deps detached from the lean Android path (Pillow, tiktoken, regex).
• Add code-puppy-bootstrap planner/wizard commands for environment detection, profile planning, guarded install steps, and post-install verification.
• Document the Android/Termux path in README.md and docs/ANDROID_INSTALL.md.
• Update CI so it first verifies the lean install does not include optional native helpers, then installs [images,search] for the historical macOS test suite that exercises image/search behavior.

Important search-support note:

Android support does not remove search support; it only prevents the PyPI ripgrep package from being installed on Android/Termux, where it is known to fail. Desktop and CI installs using [search] remain unchanged.

Android / Termux install notes

The verified fresh-phone path is:

pkg update
pkg install python git uv rust clang
uvx --from code-puppy code-puppy-bootstrap wizard

Important bootstrapping detail: install uv from Termux (pkg install uv) instead of python -m pip install uv. On Android, PyPI can fall back to building uv from source. Also install rust clang before uvx --from code-puppy ..., because uvx must resolve Code Puppy's required Python deps (notably pydantic-core) before the wizard code can run.

The wizard then handles remaining Android-native helper packages like ripgrep / proot, installs Code Puppy, and verifies code-puppy --help.

For a source checkout / editable install on Android, keep the runtime lean and do not use plain uv sync for runtime validation:

uv sync --no-dev --python "$(command -v python)"

or from an activated lean venv:

uv pip install -e '.[images]'

Plain uv sync installs the dev group; on Android that can attempt to build dev tools like ruff from Rust source and OOM. That is not the end-user runtime install path.

Desktop/macOS CI can still install the full historical image/search test surface:

uv pip install -e '.[images,search]'

Fresh-checkout Android proof

Strongest checkout test: fresh clone from upstream, then fetch the upstream PR ref
from origin — no fork remote needed for the proof.

cd ~
git clone https://github.com/mpfaffenberger/code_puppy.git code_puppy_upstream_pr496_20260622-103342
cd code_puppy_upstream_pr496_20260622-103342
git fetch origin pull/496/head:pr-496-upstream-ref
git checkout pr-496-upstream-ref
git rev-parse HEAD
# 7795b38462e93cd5c66e8b1cbd233e50644e0b5f

Lean install from that fresh upstream+PR-ref checkout succeeded on Android/Termux
using the Termux system Python (/data/data/com.termux/files/usr/bin/python3.13):

uv pip install --python .venv-lean-proof/bin/python .
Installed 78 packages
installed optional modules: []
optional-native absence: OK

Import/runtime/degradation checks from that fresh checkout:

python -c "import code_puppy; print('ok')"
ok
browser package import: OK
browser unavailable message: Playwright is not installed in this environment. Browser tools require the optional 'playwright' dependency (install code-puppy[browser]) on a supported platform.
grep error with rg hidden from PATH: ripgrep (rg) not found. Please install ripgrep to use this tool.
grep with Termux system rg on PATH: error=None, matches found
code-puppy --help: OK
code-puppy-bootstrap detect: Android/Termux detected
code-puppy-bootstrap plan --profile auto: android-termux-lean
uv run --no-dev --python "$(command -v python)" code-puppy --help: OK

Proof artifacts from this device:

• outputs/pr496-upstream-pr-ref-20260622-103342.log — strongest proof: upstream clone, upstream pull/496/head ref, Termux system Python, documented uv sync --no-dev, optional-native absence, imports, browser/search graceful degradation, system-rg search, bootstrap, and uv run --no-dev all passed.
• outputs/pr496-fresh-checkout-20260622-102330.log — plain uv sync dev-env attempt; failed building ruff, confirming uv sync is not the Android runtime path.
• outputs/pr496-squashed-bare-termux-proof.log — earlier bare-Termux sandbox proof.

Test plan

Local Android-safe checks run on this branch:

ruff check .
ruff format --check .
python -m pytest tests/test_browser_optional.py tests/test_bootstrap.py tests/test_bootstrap_wizard.py -q

Result: 22 passed.

CI workflow patch:

• PR workflow installs lean -e . first and verifies optional native modules are absent.
• It then installs .[images,search] before the full historical macOS test suite, because existing tests cover Pillow/image and ripgrep/search behavior.
• Publish workflow does the same with .[durable] first, then .[durable,images,search] for full/integration coverage.

Commit hygiene

History has been squashed into one commit for review:

7795b384 feat(android): make lean Termux installs optional-native safe

[kvandre12-commits]

Android/Termux follow-up after testing in a bare proot-style Termux sandbox:

• Confirmed a compiler-free Android install is not realistic because pydantic-core is unavoidable and has no Android wheel; the wizard now detects and installs the required Termux toolchain (rust + clang) alongside ripgrep/proot.
• Moved Pillow out of base into a new [images] extra and guarded image-tool imports so lean installs do not crash when Pillow is absent.
• Dropped pydantic-ai-slim[openai] from base to avoid pulling tiktoken + regex native builds; Code Puppy keeps its direct openai dependency, and code_puppy.model_factory imports successfully without tiktoken.
• Added docs/ANDROID_INSTALL.md with the honest Termux flow and troubleshooting.

Validation performed on-device:

• ruff check --fix + ruff format on changed files: pass
• pytest tests/test_bootstrap.py tests/test_bootstrap_wizard.py -q -o addopts="": 21 passed
• Fresh venv base install from this branch: PIL, tiktoken, and regex absent; code_puppy.model_factory import OK
• Bare sandbox dry-run selects android-termux-lean and plans: pip install uv -> pkg install -y rust clang ripgrep proot -> base Code Puppy install
• Sandbox install with toolchain visible succeeds, with PIL/tiktoken/regex absent and model_factory import OK

Note: full suite with no coverage got to 8016 passed before stopping on an unrelated existing find_available_port expectation (bind() without listen() still lets the connect-based probe report the port available). I did not scope-creep that into this PR.

[kvandre12-commits]

Update / handoff note for Mike:

I closed #494 as superseded by this PR so there is one clean upstream lane.

The intended split is:

1. This PR (feat: support lean Android/Termux bootstrap with optional native deps #496): minimal Code Puppy core that can actually install on Android/Termux

   • keeps native-only / heavy deps out of the base install path
   • gives constrained environments a lean bootstrap path
   • verified by real Android/Termux install checks, not only resolver dry-runs

2. DroidPuppy: Android overlay + lite installer + agent orchestration layer

   • lives outside upstream core so Code Puppy stays small and general-purpose
   • installs as normal Code Puppy plugins via the user/project plugin tiers
   • carries Android-native tools, browser/ADB/CDP helpers, local evidence intake, and now the first operational-world spine

Reference implementation / companion overlay:

• Repo: https://github.com/kvandre12-commits/DroidPuppy
• Recent commit: kvandre12-commits/DroidPuppy@cd1c2f3
• Overlay installer: https://github.com/kvandre12-commits/DroidPuppy/blob/main/scripts/install_overlay.py
• Operational world contract/docs: https://github.com/kvandre12-commits/DroidPuppy/blob/main/docs/OPERATIONAL_WORLD.md
• Generated plugin/tool index: https://github.com/kvandre12-commits/DroidPuppy/blob/main/docs/PLUGIN_REFERENCE.md

Why this matters: upstream only needs to merge the minimal installability/bootstrapping pieces. The Android-specific agent/orchestration machinery can remain a plugin overlay, proving the architecture without turning Code Puppy core into a phone-shaped dependency piñata.