stablyai / stablyai/orca

Improve optional helper setup and desktop renderer browser guidance

Open
#8,959 0 comments 0 reactions 1 assignee Claimed by @OrcaWin View on GitHub
enhancement
Dominant language
TypeScript
Stars
72.1k
Forks
4.7k
Avg merge
14h 54m
Merged PRs (30d)
520

Description

## Problem

The desktop development workflow exposes two confusing failure modes:

1. `pnpm dev` starts successfully even when the optional macOS Computer Use helper has not been built, but setup actions fail later with `Orca Computer Use.app was not found` and no development-specific recovery path.
2. Vite prints the Electron renderer URL as a normal localhost link. Opening `/` in a browser loads the desktop application without Electron's preload bridge and shows the generic root renderer error.

## Root cause

The dev runner has no optional-helper preflight or opt-in preparation path. Computer Use actions can also race the initial helper-status request. Separately, the renderer entry statically imports the Electron application before checking whether `window.api` was installed by preload.

## Acceptance criteria

- Ordinary `pnpm dev` remains usable when the optional macOS helper or Xcode toolchain is unavailable.
- A missing or incomplete helper produces one actionable development warning.
- A valid `ORCA_COMPUTER_MACOS_HELPER_APP_PATH` override follows the same executable validation used at runtime.
- Developers can explicitly request one-time helper preparation without adding cost to every startup.
- Computer Use setup cannot invoke `openSetup` while helper status is loading, unknown, or unavailable.
- A normal browser opening the desktop renderer entry does not import `App`; it receives a clear explanation and the development `/web-index.html` route.
- Electron startup remains unchanged when the preload bridge exists.
- Focused tests cover the production runner and actual renderer-entry wiring.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.