Declare Intel macOS unsupported for the local backend (#889) + Windows portable-install docs (#766 follow-up) - #891
Conversation
…irst-run gate + docs (#889); Windows portable-install docs (#766 follow-up) torch >=2.3 ships no macOS x86_64 wheels (transformers 5.x needs torch >=2.6), so `uv sync` can never resolve on an Intel Mac — per the platform-parity rule the honest option is declaring the platform unsupported, not letting first launch die in a raw resolver error: - bootstrap.rs: pre-check on macOS x86_64 before any venv create / uv sync (first-run AND repair paths) fails fast with an actionable message (remote-backend escape hatch + docs link); healthy pre-torch-bump venvs are deliberately untouched. Unit test pins the message's load-bearing phrases. - BootstrapSplash: routes the failure to a dedicated localized hint (bootstrap.hint_intel_mac, all 21 locales) and suppresses the useless Retry-oriented hints for it. - README + docs/install/macos.md (+ troubleshooting #9): every Intel-Mac support claim now says UI-installs-but-backend-cannot-run, including the from-source path (also broken); remote backend documented as the only use. - release.yml: #889 note on the macos-15-intel leg — artifact is UI-only; keep-or-drop is an owner call, deliberately not changed here. - docs/install/windows.md: new "Portable install (Windows)" section promised in #766 — custom MSI wizard folder / msiexec INSTALLDIR=..., what lives in OmniVoiceStudio-Data next to the exe, and the Program-Files-greyed-out why. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (28)
📝 WalkthroughWalkthroughThis PR marks macOS Intel (x86_64) as unsupported for the local Python backend across docs, release workflow comments, and app behavior. Rust bootstrap code fails fast with an Intel-specific error before venv/uv operations; the frontend detects this message and surfaces a localized hint ( ChangesIntel Mac local backend unsupported
Windows portable install documentation
Estimated code review effort: 2 (Simple) | ~15 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5 | ❌ 4❌ Failed checks (4 warnings)
✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
ESLint install failed. For unrecoverable errors, disable the tool in CodeRabbit configuration. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
| Filename | Overview |
|---|---|
| frontend/src-tauri/src/bootstrap.rs | Adds intel_mac_backend_unsupported() guard at two points in ensure_venv_ready: first-run (before venv creation) and repair path (before repair sync). Uses cfg!() so the check is compiled and testable everywhere. Contract test pins the three load-bearing phrases the JSX routing depends on. Logic is sound — spawn_backend calls ensure_venv_ready, so Retry also hits the fast-fail path. |
| frontend/src/components/BootstrapSplash.jsx | Intel Mac hint detection is placed at the end of detectHints, after up to eight other hint checks accumulate results that are then silently discarded by the early return. Retry and Clean & Retry buttons remain visible even when the only hint says "retrying won't change that", contradicting the stated UX intent. |
| frontend/src/i18n/locales/en.json | Adds hint_intel_mac key with accurate English text matching the Rust message's action items. Lead phrase matches the regex in BootstrapSplash.jsx. |
| docs/install/macos.md | Old "from source works" claim for Intel removed and replaced with [!IMPORTANT] callout; DMG table row and Apple Silicon vs Intel section updated consistently. No false hope left in the doc. |
| docs/install/windows.md | New "Portable install" section explains the grayed-out option, gives two ways to install to a writable path, and shows the resulting directory layout. Closes the #766 gap cleanly. |
| .github/workflows/release.yml | Comment-only change; the macos-15-intel build leg is kept with an owner-call note. No CI logic altered. |
| README.md | Four locations updated: download badge sub-line, System Requirements table, Roadmap Desktop row, and Apple Silicon FAQ. All consistently state the UI installs but the local backend cannot run on Intel. |
| docs/install/troubleshooting.md | §9 "mlx-whisper not loading" updated to clarify it only applies to Apple Silicon — the Intel path is now obsolete. One-liner reality check added. |
Flowchart
%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[App launch / Retry] --> B[spawn_backend]
B --> C[ensure_venv_ready]
C --> D{intel_mac_backend_unsupported?}
D -- "yes (first-run path)" --> E[fail: INTEL_MAC_UNSUPPORTED_MSG]
D -- no --> F{venv exists & healthy?}
F -- yes --> G[return venv_py, backend_dir]
F -- "no / broken" --> H{intel_mac_backend_unsupported?}
H -- yes --> E
H -- no --> I[repair uv sync]
I --> G
E --> J[BootstrapStage::Failed]
G --> K[spawn uvicorn]
K --> L[BootstrapStage::Ready]
J --> M[detectHints in JSX]
M --> N{message contains Intel phrase?}
N -- yes --> O[return hint_intel_mac ONLY]
N -- no --> P[accumulate other hints]
O --> Q[Show hint: retrying won't change that]
P --> R[Show Retry / Clean & Retry buttons]
Q --> R
%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
A[App launch / Retry] --> B[spawn_backend]
B --> C[ensure_venv_ready]
C --> D{intel_mac_backend_unsupported?}
D -- "yes (first-run path)" --> E[fail: INTEL_MAC_UNSUPPORTED_MSG]
D -- no --> F{venv exists & healthy?}
F -- yes --> G[return venv_py, backend_dir]
F -- "no / broken" --> H{intel_mac_backend_unsupported?}
H -- yes --> E
H -- no --> I[repair uv sync]
I --> G
E --> J[BootstrapStage::Failed]
G --> K[spawn uvicorn]
K --> L[BootstrapStage::Ready]
J --> M[detectHints in JSX]
M --> N{message contains Intel phrase?}
N -- yes --> O[return hint_intel_mac ONLY]
N -- no --> P[accumulate other hints]
O --> Q[Show hint: retrying won't change that]
P --> R[Show Retry / Clean & Retry buttons]
Q --> R
Comments Outside Diff (2)
-
frontend/src/components/BootstrapSplash.jsx, line 512-526 (link)Retry/Clean-&-Retry buttons shown despite hint saying "retrying won't change that"
The failure section renders the Retry and Clean & Retry buttons unconditionally for every failure kind. When the only hint is
bootstrap.hint_intel_mac, every locale string explicitly tells the user "retrying won't change that," yet both action buttons remain visible below. A user who reads the hint and then sees the buttons will try them anyway. While each retry does fail fast (a few milliseconds, becausespawn_backend→ensure_venv_ready→ Intel Mac check → immediate fail), the contradiction erodes trust and causes repeated confirmation dialogs from Clean & Retry.The intent expressed in the comment — "retrying can never help — show only this" — applies to the buttons too. The
detectHintsresult is already available in the render scope; drive button visibility from it.Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
-
frontend/src/components/BootstrapSplash.jsx, line 82-109 (link)The
detectHintsfunction pushes up to eight hints into thehintsarray before reaching the Intel Mac check at line 104. Because the early return discards whatever was accumulated, those evaluations are wasted when the Intel Mac phrase is present. More importantly, this is a maintenance trap: a future hint check whose regex accidentally matches a substring ofINTEL_MAC_UNSUPPORTED_MSG(e.g., a new pattern containing "can't" or "install") would push its hint tohints, only to have it silently discarded by the early return — making the new check appear to work everywhere except on an Intel Mac failure, which is hard to spot in a non-Intel-Mac dev environment.Moving the Intel Mac block to the very top of
detectHints(before anyhints.push) would make the exclusivity explicit and avoid the accumulate-then-discard hazard.
Reviews (1): Last reviewed commit: "fix(platform): declare Intel-Mac local b..." | Re-trigger Greptile
1 participant
What
Two documentation + policy fixes:
#889 — Intel-Mac first launch broken (P0): declare the platform unsupported
torch 2.8.0 (pinned in
uv.lock) has no macOS x86_64 wheels — PyTorch dropped Intel-Mac after 2.2.x, and transformers 5.x needs torch ≥2.6, so a platform-marker downgrade is infeasible. Per the platform-parity hard rule, the only honest option left is declaring Intel macOS unsupported for the local backend. This PR implements that declaration:frontend/src-tauri/src/bootstrap.rs): ontarget_os = macos+target_arch = x86_64,ensure_venv_readynow fails fast before creating a venv or attempting anyuv sync(first-run and repair paths) with a clear, actionable message — "Intel Macs can't run the local AI backend — PyTorch no longer ships Intel-Mac (macOS x86_64) builds…" plus the remote-backend escape hatch (Settings → Sharing → Remote backend) and a docs link — instead of a raw uv resolver error after minutes of downloads. A healthy already-synced venv (pre-torch-bump install) is deliberately not blocked. Unit test pins the message's load-bearing phrases.BootstrapSplash.jsx+ all 21 locales): the failure routes to a dedicated localized hint (bootstrap.hint_intel_mac) and suppresses the Retry/Clean-&-Retry-oriented hints, which can never help here.[!IMPORTANT]note at the top for Intel users — no false hope, including the from-source path (it fails the same resolution); DMG table row + "Apple Silicon vs Intel" section updated to match.docs/install/troubleshooting.md§9 gets a one-line reality update.macos-15-intelbuild leg is kept — a comment now flags that the artifact is effectively UI-only under [P0] Intel-Mac first launch is broken: uv.lock pins torch 2.8.0, which has no macOS x86_64 wheels #889 and that keeping vs. dropping it is an owner call.#766 follow-up — "Portable install (Windows)" docs section
docs/install/windows.mdgains the section promised when closing #766: why Portable is greyed out after a default Program Files install, how to enable it (custom folder in the MSI wizard ormsiexec /i … INSTALLDIR="D:\Apps\OmniVoice"), and exactly what lives next to the exe (OmniVoiceStudio-Data\withconfig.json,env\,data\models\).Gates
cargo check -q— clean (only pre-existingsetup.rsunreachable-expression warning, untouched by this diff); newintel_mac_message_keeps_its_contract_phrasestest passesuv run pytest tests/ -q -k "readme or features or docs or inventory"— 63 passed, 1 skippedtests/test_no_hardcoded_cjk.py— passes (new CJK strings live only infrontend/src/i18n/locales/)vitest run675/675 passed;oxlint0 errors;oxfmtcleanCloses #889. Follow-up to #766.
🤖 Generated with Claude Code
Summary
Behavior
flowchart TD A[App starts bootstrap] --> B{macOS Intel x86_64?} B -- No --> C[Continue normal venv/uv sync flow] B -- Yes --> D[Set bootstrap stage = Failed] D --> E[Show Intel-Mac unsupported message] E --> F[Suggest remote backend / docs]UI sketch