diff --git a/plan.md b/plan.md new file mode 100644 index 0000000000..45d3eabc39 --- /dev/null +++ b/plan.md @@ -0,0 +1,320 @@ +# WSL Local Server Implementation Backlog + +This backlog assumes Electron only. +It is ordered chronologically. +Each task is intended to be small enough for a new engineer to pick up directly. + +## 01 Foundation + +- [ ] Add a new persisted `localServer` settings key in `packages/desktop-electron/src/main/constants.ts`. +- [ ] Define a `LocalServerMode` type with `"windows" | "wsl"` in the Electron preload types. +- [ ] Define a persisted `LocalServerConfig` shape in the Electron preload types. +- [ ] Include `mode`, `distro`, onboarding metadata, root acknowledgements, and mismatch acknowledgements in `LocalServerConfig`. +- [ ] Remove the old `WslConfig` type from `packages/desktop-electron/src/preload/types.ts`. +- [ ] Remove the old `WSL_ENABLED_KEY` constant and stop adding new code that depends on it. +- [ ] Add a single source of truth helper in Electron main for reading `LocalServerConfig` from `electron-store`. +- [ ] Add a single source of truth helper in Electron main for writing `LocalServerConfig` to `electron-store`. +- [ ] Ignore any legacy `wslEnabled` value during reads of the new Local Server config. +- [ ] Add explicit comments in the new config helpers that this feature is Electron-only and replaces the legacy WSL boolean. + +## 02 Main-Process Local Server Controller + +- [ ] Create a dedicated Electron main module for Local Server orchestration, for example `packages/desktop-electron/src/main/local-server.ts`. +- [ ] Move local runtime orchestration out of ad hoc startup code and into the Local Server controller. +- [ ] Define an in-memory `LocalServerState` shape for runtime status, current job, current transcript, and startup failure. +- [ ] Keep `LocalServerState` in memory only; do not persist runtime status or raw logs. +- [ ] Add a typed event emitter inside the Local Server controller. +- [ ] Support one active Local Server job at a time in the controller. +- [ ] Add a helper to reject or cancel a previous Local Server job before starting a new one. +- [ ] Allocate the loopback port once per app launch and keep it stable for all Local Server restarts in that launch. +- [ ] Allocate the local auth password once per app launch and keep it stable for all Local Server restarts in that launch. +- [ ] Expose a controller method to return a full current Local Server snapshot. +- [ ] Expose a controller method to subscribe to Local Server events. +- [ ] Expose a controller method to update persisted Local Server config. +- [ ] Expose a controller method to run a specific wizard step. +- [ ] Expose a controller method to apply Local Server runtime changes in the background. +- [ ] Expose a controller method to cancel the current Local Server job. +- [ ] Expose a controller method to open a terminal for the selected distro. + +## 03 Windows Local Runtime Path + +- [ ] Move the existing Windows local sidecar startup path from `packages/desktop-electron/src/main/server.ts` into the Local Server controller. +- [ ] Keep the existing Windows local runtime behavior unchanged when `mode === "windows"`. +- [ ] Keep the existing eager local startup behavior unchanged for Windows local mode. +- [ ] Keep the existing loopback no-proxy behavior unchanged for Windows local mode. +- [ ] Update the controller snapshot so Windows local mode reports a distinct runtime key instead of the old implicit bare `sidecar` assumption. + +## 04 WSL Process Helpers + +- [ ] Add a helper to spawn `wsl.exe` with a selected distro and stream stdout/stderr lines. +- [ ] Standardize all WSL command execution on `wsl.exe -d -- bash -lc ...`. +- [ ] Add a helper to kill the currently spawned WSL child process when a job is canceled. +- [ ] Do not call `wsl --terminate ` as part of normal cancel behavior. +- [ ] Add a helper to run a short command and collect stdout/stderr for probe steps. +- [ ] Add a helper to resolve the selected distro home directory via `~`. +- [ ] Add a helper to run `command -v opencode` inside the selected distro. +- [ ] Add a helper to resolve `opencode --version` inside the selected distro. +- [ ] Add a helper to detect the selected distro default username via shell commands. +- [ ] Add a helper to detect whether the selected distro default user is `root`. +- [ ] Add a helper to detect whether `bash` exists in the selected distro. +- [ ] Add a helper to detect whether `curl` exists in the selected distro. +- [ ] Add a helper to run `opencode upgrade ` inside the selected distro. +- [ ] Add a helper to launch the Local Server with a resolved absolute executable path instead of bare `opencode`. + +## 05 WSL Runtime and Distro Probes + +- [ ] Add a helper to probe whether `wsl.exe` is available and usable. +- [ ] Add a helper to list installed distros with `wsl --list --verbose`. +- [ ] Add a helper to list online distros with `wsl --list --online`. +- [ ] Do not add system-distro filtering logic; keep all returned distros visible. +- [ ] Add probe parsing for `WSL 1` vs `WSL 2` from installed distro data. +- [ ] Treat `WSL 2` as required for first-class onboarding. +- [ ] Add explicit probe output for `missing bash`. +- [ ] Add explicit probe output for `missing curl`. +- [ ] Add explicit probe output for `cannot execute commands in distro`. +- [ ] Add explicit probe output for `default user is root`. +- [ ] Add explicit probe output for `distro not found`. + +## 06 WSL Install Helpers + +- [ ] Add a helper to run elevated `wsl --install --no-distribution` from Electron main. +- [ ] Implement that elevation path with a shell-based helper invocation rather than a bundled helper binary. +- [ ] Add a helper to install a distro with `wsl --install -d --web-download --no-launch`. +- [ ] Do not auto-install a default distro as part of the WSL runtime install step. +- [ ] Add a helper to detect whether a WSL install requires reboot. +- [ ] Add a helper to expose a `Restart now` action. +- [ ] Add a helper to mark onboarding as pending reboot when the user chooses `Later`. + +## 07 OpenCode Runtime Detection and Repair + +- [ ] Resolve `command -v opencode` on each startup when `mode === "wsl"`. +- [ ] Re-resolve `command -v opencode` on each explicit WSL apply/retry action. +- [ ] Compare the detected WSL `opencode` version to the desktop app version. +- [ ] Record mismatch acknowledgement once per resolved path plus version pair. +- [ ] Keep version mismatch non-blocking. +- [ ] Treat `Use anyway` as sufficient to complete the OpenCode step with warning. +- [ ] Implement `Install matching version` by running `opencode upgrade ` first. +- [ ] If `opencode upgrade` hangs, prompts, or fails, mark the repair attempt failed and stop automation. +- [ ] Surface the failed upgrade transcript in the Local Server UI. +- [ ] Do not add an automatic fallback installer path after `opencode upgrade` fails. +- [ ] Surface manual recovery commands instead. + +## 08 Startup Handshake and App Boot + +- [ ] Replace the current success-only startup payload with a ready-or-failed startup union. +- [ ] Include local runtime metadata in the startup payload. +- [ ] Include the local runtime key in the startup payload. +- [ ] Include runtime variant details in the startup payload. +- [ ] Include selected distro in the startup payload when `mode === "wsl"`. +- [ ] Include loopback URL and credentials in the startup payload even when the local runtime later fails health. +- [ ] Include startup failure step and message in the startup payload when the local runtime fails. +- [ ] Update `packages/desktop-electron/src/main/index.ts` to initialize Local Server through the controller. +- [ ] Keep the loading overlay generic and do not add WSL-specific overlay phases in v1. +- [ ] Add a startup health-verdict timeout for WSL local startup so the app can open after failure. +- [ ] Scope the startup timeout to the local health verdict only, not to sqlite migration. +- [ ] Open the main window after startup reaches a ready-or-failed local verdict. + +## 09 IPC and Preload API + +- [ ] Add a namespaced `localServer` API to the Electron preload surface. +- [ ] Implement `localServer.getState()`. +- [ ] Implement `localServer.subscribe()` with unsubscribe support. +- [ ] Implement `localServer.setConfig()`. +- [ ] Implement `localServer.runStep()`. +- [ ] Implement `localServer.apply()` for background runtime switching. +- [ ] Implement `localServer.cancelJob()`. +- [ ] Implement `localServer.openTerminal()`. +- [ ] Implement `localServer.restartNow()` for reboot-required flows. +- [ ] Implement `localServer.copyTranscript()` or equivalent transcript fetch action. +- [ ] Emit typed step/state events from main to renderer. +- [ ] Emit raw stdout/stderr line events from main to renderer. +- [ ] Remove `getWslConfig` from the preload API. +- [ ] Remove `setWslConfig` from the preload API. +- [ ] Remove `get-wsl-config` and `set-wsl-config` IPC handlers. + +## 10 Renderer Startup and Platform Wiring + +- [ ] Update the desktop renderer startup resource to consume the new startup union shape. +- [ ] Build the Local Server `ServerConnection.Sidecar` from structured startup metadata instead of hardcoding `variant: "base"`. +- [ ] Keep the visible Local Server display name as `Local Server` in both Windows and WSL modes. +- [ ] Add a WSL badge or subtitle in the row UI instead of renaming the server. +- [ ] Change the implicit local fallback key to follow the configured Local Server runtime. +- [ ] Remove all uses of `window.__OPENCODE__.wsl` from the renderer. +- [ ] Derive WSL picker/path behavior from structured Local Server state instead of a global boolean. +- [ ] Update `createPlatform()` so WSL path conversion only activates when Local Server mode is WSL. +- [ ] Default native pickers to the selected distro home path when Local Server mode is WSL. +- [ ] Keep native pickers on normal Windows behavior when Local Server mode is Windows. + +## 11 Distro-Aware Path Conversion + +- [ ] Update `packages/desktop-electron/src/main/apps.ts` so `wslPath()` accepts a distro parameter. +- [ ] Stop using the ambient default WSL distro for path conversion. +- [ ] Use the selected Local Server distro for all `~` resolution. +- [ ] Use the selected Local Server distro for all Windows-to-Linux path conversion. +- [ ] Use the selected Local Server distro for all Linux-to-Windows path conversion. +- [ ] Update open-path behavior to use distro-aware conversion when Local Server mode is WSL. + +## 12 App Server Model Changes + +- [ ] Introduce a distinct explicit key for Windows Local Server. +- [ ] Keep WSL Local Server keyed by distro identity. +- [ ] Update `packages/app/src/context/server.tsx` so Windows local and WSL local do not collapse into the same project-history bucket. +- [ ] Update `projectsKey()` to keep Windows local and WSL local histories separate. +- [ ] Update `isLocal()` so WSL Local Server still counts as local. +- [ ] Ensure Local Server key changes force the expected remount behavior through `ServerKey` in `packages/app/src/app.tsx`. +- [ ] If Local Server is currently active, make successful runtime switches follow the new local key automatically. + +## 13 Manage Servers Dialog Shell + +- [ ] Add a pinned `Local Server` row to `packages/app/src/components/dialog-select-server.tsx` list mode. +- [ ] Extract a dedicated Local Server page component instead of growing `dialog-select-server.tsx` further. +- [ ] Add a dialog mode or route that opens the dedicated Local Server page from the server list. +- [ ] Keep existing HTTP add/edit/delete/default flows untouched while adding the Local Server entry. +- [ ] Add an initial-view prop so the Manage Servers dialog can open directly to Local Server. + +## 14 Local Server Wizard + +- [ ] Implement a dedicated Local Server wizard component. +- [ ] Implement step order exactly as `WSL -> Distro -> OpenCode -> Switch`. +- [ ] Allow the user to go back and edit earlier steps. +- [ ] Persist wizard progress inside `LocalServerConfig`. +- [ ] Auto-resume the wizard after app relaunch when onboarding is incomplete. +- [ ] Auto-resume the wizard after reboot when onboarding was waiting for restart. +- [ ] Mark the wizard complete only after Local Server hot restart succeeds and health passes. + +## 15 WSL Step UI + +- [ ] Show current WSL runtime probe result in the WSL step. +- [ ] Add an `Install WSL` action that starts elevated `wsl --install --no-distribution`. +- [ ] Show reboot-required state in the WSL step when the install path requires restart. +- [ ] Add `Restart now` and `Later` actions. +- [ ] Keep the WSL step editable after the user returns from reboot. + +## 16 Distro Step UI + +- [ ] Show installed distros with explicit probe status in the Distro step. +- [ ] Show quick install actions for `Debian` and `Ubuntu 24`. +- [ ] Show an `Other distro...` action that reads from the online distro list. +- [ ] After distro install, auto-select the newly installed distro and continue probing automatically. +- [ ] Surface `WSL 1` as unsupported with manual conversion instructions. +- [ ] Surface `missing bash` as an explicit unsupported reason. +- [ ] Surface `missing curl` as an explicit unsupported reason. +- [ ] Surface `cannot execute commands` as an explicit unsupported reason. +- [ ] Surface `default user is root` as a warning in the Distro step. +- [ ] Require explicit root acknowledgement once per distro. +- [ ] Keep all distros visible even when unsupported. +- [ ] If the selected distro disappears, show an explicit missing-distro error instead of auto-switching away. + +## 17 OpenCode Step UI + +- [ ] Show the resolved absolute `opencode` path for the selected distro. +- [ ] Show the detected `opencode` version for the selected distro. +- [ ] Show version mismatch as a non-blocking warning. +- [ ] Add `Use anyway` in the mismatch state. +- [ ] Add `Install matching version` in the mismatch state. +- [ ] Keep mismatch acknowledgement scoped to path plus version. +- [ ] Re-warn only when the resolved path or resolved version changes later. +- [ ] If `command -v opencode` resolves nothing, show explicit manual recovery guidance. +- [ ] If `opencode upgrade` fails, keep the step incomplete and show the transcript. + +## 18 Switch Step UI + +- [ ] Add a `Switch Local Server` action that applies the new Local Server runtime in the background. +- [ ] Keep remote sessions usable while the Switch step runs. +- [ ] Reuse the current app-launch port and password during background Local Server restarts. +- [ ] Keep the Local Server active selection on Local Server when the switch succeeds and Local Server was already active. +- [ ] Show success only after `/global/health` succeeds for the new runtime. +- [ ] If background apply fails, show a `Restart OpenCode` fallback prompt. + +## 19 Local Server Status Dashboard + +- [ ] Replace the wizard with a steady-state dashboard after onboarding completes. +- [ ] Show current mode on the dashboard. +- [ ] Show selected distro on the dashboard when in WSL mode. +- [ ] Show current Local Server health on the dashboard. +- [ ] Show current failure state on the dashboard when the last startup or apply failed. +- [ ] Show version mismatch warning on the dashboard when the user chose `Use anyway`. +- [ ] Show root warning on the dashboard when the selected distro is root-backed and acknowledged. +- [ ] Do not show stale last-known-good probe values outside the current failure context. +- [ ] Add dashboard actions for `Retry`, `Open terminal`, and transcript copy. + +## 20 Live Diagnostics + +- [ ] Add a live diagnostics panel to the Local Server UI. +- [ ] Stream merged stdout/stderr lines into the panel while jobs are running. +- [ ] Keep the panel usable for startup failures from the current app launch. +- [ ] Retain the full Local Server transcript only for the current app launch. +- [ ] Clear the retained transcript on full app relaunch. +- [ ] Show exact commands in the diagnostics details area. +- [ ] Make `Copy commands` copy the same transcript content as the transcript-copy action. +- [ ] Keep diagnostics collapsible by default. + +## 21 Connection Error and Deep Linking + +- [ ] Add a direct `Open Local Server` CTA to the existing `ConnectionError` screen when the failing server is Local Server. +- [ ] Make that CTA open the Manage Servers dialog directly to the Local Server page. +- [ ] When Local Server startup failed earlier in the same launch, jump the Local Server UI directly to the failing step or dashboard state. +- [ ] Keep existing retry behavior for non-local remote servers unchanged. + +## 22 Runtime Apply and Background Behavior + +- [ ] Apply Local Server runtime changes in the background when the active server is remote. +- [ ] Do not navigate away from a remote session during a Local Server background apply. +- [ ] Keep Local Server config separate from active/default server selection logic. +- [ ] Do not auto-select Local Server just because its runtime config changed. +- [ ] Do not auto-change the user's default remote server selection when Local Server mode changes. + +## 23 Main Window Startup Failure Handling + +- [ ] If WSL Local Server fails during startup, keep the app launch going after the health-verdict timeout. +- [ ] Represent that failure in the startup payload instead of throwing away initialization. +- [ ] Keep the Local Server row present in the server list even when startup failed. +- [ ] Mark the Local Server row unhealthy when startup failed. +- [ ] Keep the startup loading overlay generic even in this failed case. + +## 24 API Cleanup and Legacy Removal + +- [ ] Remove the old hidden WSL settings UI branch from `packages/app/src/components/settings-general.tsx`. +- [ ] Remove legacy renderer calls that assume a boolean WSL mode. +- [ ] Remove legacy IPC registrations for the boolean WSL config. +- [ ] Remove legacy preload typing for the boolean WSL config. +- [ ] Remove legacy main-process store helpers that only read/write `wslEnabled`. + +## 25 Manual Recovery and Power Actions + +- [ ] Implement `Open terminal` as `open selected distro shell only` and do not auto-run recovery commands. +- [ ] Make `Open terminal` target the selected distro explicitly. +- [ ] Add a transcript copy action that is available even after failed jobs. +- [ ] Keep manual recovery command text aligned with the actual commands the controller runs. +- [ ] Include manual commands for WSL 1 conversion in the Distro step. +- [ ] Include manual commands for missing `curl` in the Distro or OpenCode step as appropriate. +- [ ] Include manual commands for PATH install version repair in the OpenCode step failure state. + +## 26 Verification and QA + +- [ ] Verify Windows Local Server behavior is unchanged when `mode === "windows"`. +- [ ] Verify the app still boots normally with no Local Server config present. +- [ ] Verify the app opens after a WSL startup failure instead of hanging forever. +- [ ] Verify `Install WSL` can reach a reboot-required state and resume after relaunch. +- [ ] Verify `Restart now` and `Later` both preserve onboarding state correctly. +- [ ] Verify Debian quick install auto-selects the new distro and continues onboarding. +- [ ] Verify Ubuntu 24 quick install auto-selects the new distro and continues onboarding. +- [ ] Verify `Other distro...` uses the live online catalog. +- [ ] Verify a WSL 1 distro surfaces manual conversion instructions. +- [ ] Verify a distro missing `bash` surfaces an explicit unsupported reason. +- [ ] Verify a distro missing `curl` surfaces an explicit unsupported reason. +- [ ] Verify a root-backed distro requires acknowledgement once per distro. +- [ ] Verify PATH-installed `opencode` is re-resolved on each startup. +- [ ] Verify mismatch acknowledgement only reappears when path or version changes. +- [ ] Verify `Use anyway` completes onboarding with a lingering dashboard warning. +- [ ] Verify `Install matching version` runs `opencode upgrade `. +- [ ] Verify an upgrade hang or prompt can be canceled and leaves a usable transcript. +- [ ] Verify Local Server hot restart keeps the same port and password within one app launch. +- [ ] Verify Local Server hot restart does not interrupt an active remote session. +- [ ] Verify active Local Server selection follows the new local key after a successful runtime switch. +- [ ] Verify Windows local and WSL local project histories remain separate. +- [ ] Verify the `ConnectionError` CTA opens the Local Server page directly. +- [ ] Verify selected-distro path conversion is used everywhere in WSL mode. +- [ ] Verify selected-distro home is used as the picker default in WSL mode. +- [ ] Verify deleting the selected distro produces an explicit error instead of silent fallback. +- [ ] Verify transcripts are only retained for the current app launch.