stablyai / stablyai/orca

[Feature]: WSL native projects — first-class Add Project source (POSIX-native, à la VSCode)

Open
#8,286 1 comment 3 reactions 1 assignee Claimed by @OrcaWin View on GitHub
enhancement os:Windows
Dominant language
TypeScript
Stars
71.3k
Forks
4.7k
Avg merge
14h 54m
Merged PRs (30d)
520

Description

### Problem or use case

Orca fully supports running a **WSL shell**, but a **project** is only ever a Windows-hosted entity. A repo that lives inside the WSL filesystem is registered as a Windows **UNC path** (`\\wsl.localhost\\home\\`) and treated as a transparent routing sub-mode of the `local` host. There is no first-class "open a WSL project" entry point, the file explorer surfaces UNC paths instead of the native POSIX path, and the WSL shell pivot relies on `cwd`-string sniffing rather than the project's resolved runtime.

Compared to VSCode's WSL Remote — the closest-to-native Windows experience — this is inconvenient, and it has produced a recurring class of path-translation bugs (#6908, #7021, #7649, #6331).

This supersedes the stub in #5311 with a concrete, code-grounded design.

### Proposed solution

Make a WSL-filesystem project a **first-class, user-selectable source in Add Project** (a peer of `Local` / `SSH` in the UI, à la VSCode), with **POSIX path recognition/display** and an **automatic WSL shell default** — while **reusing** Orca's existing WSL routing rather than introducing a new execution host.

**Approach A (chosen): surface the existing WSL routing, no new host.** The runtime resolver (`src/shared/project-execution-runtime.ts`) already threads `wslDistro` through every Git call, so WSL stays a `local` sub-mode; a full SSH-style provider would duplicate that layer.

Design highlights (full spec on the branch: `docs/reference/wsl-native-project-support.md`):

1. **Data model & identity** — a WSL project is a `Repo` with UNC `path`, `connectionId=null`, and `localWindowsRuntimePreference={kind:'wsl',distro}` set explicitly at add time (removes reliance on incidental `cwd` sniffing, the root cause of #6908). Add display-only derivations `getRepoDisplayPath` (UNC→POSIX) and a runtime-based `isWslRepo`.
2. **Add Project (WSL source)** — detect distros (`listWslDistrosAsync`), browse the distro in **POSIX**, store as UNC (`toWindowsWslPath`), validate via `wslUncDirectoryExists` (9P-safe). Repo-add branches for WSL like it does for SSH so UI and CLI resolve identical refs (#6908).
3. **Display** — file explorer / titles show the POSIX path; project rows show a **`WSL: ` badge** (VSCode remote-indicator parallel).
4. **Shell pivot (absorbs #5111)** — default shell decided from the resolved runtime; per-project "Default Shell" override with precedence *creation override > per-project > runtime default (WSL) > global*.
5. **Gap closures** — enable **worktree-base watching for WSL roots** (currently skipped at `worktree-base-directory-watch-targets.ts:131`) so new worktrees surface without a manual refresh; unify UI/CLI repo-add normalization.
6. **Edge cases** — WSL missing/stopped/removed surfaced via the resolver's `repair-required` states; keep the "throw, never silently fall back to host Git" behavior.

### Scope

**In:** WSL Add Project source, POSIX display + badge, runtime-driven shell default + per-project override, worktree-base watching for WSL, UI/CLI repo-add unification.

**Out (non-goals):** no new `ExecutionHostId` (`wsl:`); no change to canonical UNC storage (POSIX is display-only); WSL-over-SSH; rich terminal POSIX link clickability (#8156, adjacent).

### Alternatives or additional context

- **Approach B** — promote WSL to a first-class execution host (SSH-style `WslGit/Filesystem/PtyProvider`). Cleanest/closest to VSCode internally, but a large refactor that duplicates the existing transparent-routing layer and fights the team's "WSL = local sub-mode" decision. Rejected as over-engineering for the same user-visible outcome.
- Related: supersedes #5311, absorbs #5111; addresses the #6908 / #7021 path-normalization class; benefits from (but does not block on) PR #7968 (managed Linux file-watching host).

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.