## Summary
- The missing-boxlite advice told users to run `pip install
'raven[sandbox]'`, which is wrong twice over: the `raven` name on
package indexes resolves to an unrelated project, and a global pip
install bypasses the uv environment raven actually runs in (#640).
- Added `boxlite_install_hint()` to `raven.sandbox`: it resolves the
pinned boxlite requirement from the installed distribution metadata
(falling back to the bare name when metadata is absent) and renders a
copy-pasteable command targeting the running interpreter, e.g. `uv pip
install --python /path/to/venv/bin/python boxlite==0.9.5`.
- The onboarding screen keeps its translatable line in the zh catalog
and prints the command on its own untranslatable line;
`build_executor`'s ImportError message uses the same hint.
- The two init-failure messages that fire after the boxlite import
already succeeded no longer suggest a reinstall; they keep the platform
bullets naming the actual causes.
## Type
- [x] Fix
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
Commands run on macOS, Python 3.12, on top of a clean checkout of main:
- `uv run pytest tests/test_sandbox_unit.py
tests/test_cli_onboard_commands.py tests/test_i18n_boundary.py
tests/test_i18n_prompts.py -q` -> 467 passed. The new tests
(TestBoxliteInstallHint, TestInitFailureAdvice, one TestBuildExecutor
case, one onboard screen case) were each watched failing before the fix.
- `uv run --frozen --python 3.12 --all-extras pytest -q` -> 27002
passed, 109 skipped, 21 failed. The 21 failures reproduce identically on
unmodified main (verified by stashing this change):
`test_agents_research_tools.py` (13),
`test_agents_research_verbatim_sink.py` (5),
`test_simulation_scenario.py` and `test_simulation_suite.py` (2),
`test_rpc_files.py::test_a_host_without_libreoffice_says_so` (1,
LibreOffice not installed locally). None touch the changed modules.
- `uv run ruff check` and `ruff format --check` on the six touched files
-> clean.
- `make lint-imports` -> 10 kept, 0 broken.
- `make check-source-language` -> pass.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
- User-visible change: three messages read differently (the onboarding
hint, the build_executor ImportError, two executor init-failure
messages). No API, config, or behavior change beyond the wording. The
hint assumes uv on PATH, which every documented install path already
requires.
- Rollback is a straight revert of this commit.
## Related Issues
Fixes#640
## Change description
> Whole-repo lint + pre-commit convention, CONFIG ONLY (no source
reformat in this PR). Python (ruff) and TypeScript (eslint + prettier)
share a 120-col margin via the committed pre-commit gate. This upgrades
main's existing basic ruff setup and adds the TS lint stack (none
existed on main).
>
> What this PR adds:
> - ruff: line-length 120; security rules
S101/S105/S106/S107/S506/S605/S607; policy per-file-ignores (tests +
accepted CLI deferred-imports + product asserts + N818, each commented);
ruff pinned <0.16.
> - eslint/prettier: shared base (`eslint.base.mjs` +
`prettier.config.mjs`); ui-tui extends it with React rules, bridge with
a Node-only config; hermes-ink vendor and generated RPC types excluded.
> - pre-commit: keeps main's hooks (conventional-commit,
detect-private-key, etc.), adds a top-level exclude and 4 local
eslint/prettier hooks; bumps the pre-commit dev dep.
> - 2 lint-surfaced fixes: PlannerContext import (F821) in the sentinel
runner; lower-cased file-local cron-heartbeat constants (N806).
(raven/config/raven.py's F821 was already fixed on main.)
>
> Sequencing: config only. `ruff check` is intentionally red on ~307
auto-fixables (I001/F401/F541/E701/E702); a SEPARATE reformat branch
runs `ruff --fix` + `ruff format` + eslint/prettier --fix to clear them
(100% auto-resolvable, zero manual). Enforcement (pre-commit install /
CI) turns on only after the reformat lands, so do not expect a green
tree from this PR alone.
>
> CLI-owned files (the reformat and several per-file-ignores touch
`raven/cli/*`) are under review by the CLI team. Judgment items (TS
no-explicit-any, no-unused-expressions, S101 convert-vs-keep, N818
rename, C90, mypy) are deferred to v2.
## Type of change
- [ ] Bug fix
- [x] New feature
- [ ] Document
- [x] Others
## Related issues (if there is)
> none
## Checklists
### Development
- [ ] Lint rules pass locally
- [ ] Application changes have been tested thoroughly
- [ ] Automated tests covering modified code pass
> config-only: `ruff check` is red on auto-fixables by design (the
reformat branch clears them); eslint/prettier configs load in both
ui-tui and bridge.
### Security
- [x] Security impact of change has been considered
- [ ] Code follows company security practices and guidelines
> Only dependency change is the dev-only pre-commit tool plus the ruff
pin; the detect-private-key hook from main is retained.
### Code review
- [x] Pull request has a descriptive title and context useful to a
reviewer
- [ ] Pull request linked to JIRA ticket when applicable
---------
Co-authored-by: Sheng Zhao <sheng.zhao@evermind.ai>
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>