feat: add installer-first onboarding and pre-download Linux browser checks - #387
Merged
Conversation
…hecks
Make the first run survive the five most common fresh-machine failures:
- Add scripts/install.sh (ported from the openadapt.ai installer pattern):
installs uv if needed, provisions Python 3.12 (managed interpreter only
when no suitable system Python exists), installs 'openadapt[browser]'
without any shell quoting on the user's side, and ends with an
environment check (OS / Python / command / browser status) plus the next
command. POSIX sh; macOS + Linux.
- README quickstart becomes installer-first; the pip two-command path stays
as the fallback directly below, with a short Requirements line
(Python 3.10-3.12).
- _browser_setup.py now probes Chromium's shared libraries via
ctypes.util.find_library before downloading on Linux; when libraries are
missing it prints the exact remedy first ('sudo python -m playwright
install-deps chromium' plus the apt alternative) and aborts cleanly, so
fresh machines no longer waste a full download on a browser that cannot
launch.
- The offline/CDN-blocked install error now names the manual command, the
HTTPS_PROXY hint, the cache-copy fallback, and the
OPENADAPT_FLOW_NO_AUTO_INSTALL opt-out.
requires-python bounds are unchanged.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
scripts/install.sh: installs uv if needed, provisions Python 3.12 (managed interpreter only when no suitable system Python exists), installsopenadapt[browser]with the bracket quoting handled internally, and ends with a doctor-style environment check (OS / Python / command / browser status) plus the next command. POSIX sh, macOS + Linux, idempotent (upgrade in place). Pattern ported from the existing openadapt.ai installer.curl … | sh); the pip two-command path stays as the fallback directly below; short Requirements line added: Python 3.10–3.12 (3.13+ not yet supported — installer provisions a suitable interpreter). No other sections restructured._browser_setup.py: before downloading Chromium on Linux, probe required shared libraries viactypes.util.find_library(cheap, offline). If any are missing, print the exact remedy FIRST (sudo python -m playwright install-deps chromium+ apt alternative line) and abort cleanly — no wasted download followed by a launch failure.HTTPS_PROXYhint, cache-copy fallback, and theOPENADAPT_FLOW_NO_AUTO_INSTALL=1opt-out.Files changed
scripts/install.sh(new, +x)openadapt_flow/_browser_setup.pyREADME.md(quickstart section only)tests/test_browser_setup.py(focused new tests; probes monkeypatched, no network)Verification
origin/main(583041f) aftergit fetchbefore branchingruff check+ruff format --checkon changed files: passpytest tests/test_browser_setup.py tests/test_install_playwright_browser.py: 36 passed, 4 skippedtest_cli_tutorial_break_it.py,test_cli_tutorial_next_steps.py): 23 passedmypy openadapt_flow/_browser_setup.py: no issuespython -c "import openadapt_flow": cleansh -n scripts/install.sh: syntax OK; env-check block exercised locally on macOS arm64Notes / deviations
pyproject.toml:requires-pythonbounds untouched as instructed; no in-package version-check messaging exists (pip itself surfaces the bound), so nothing to improve there.docs/in this repo on main; the installer-first docs surface lives in openadapt-maintenance (docs.openadapt.ai), which is outside this PR's scope.