openwork/prd-opencode-install.md

PRD — OpenCode CLI Install + Engine Bootstrap (OpenWork)

Summary

OpenWork currently requires the opencode CLI to already be installed and available on the user’s PATH. This is a major onboarding cliff for non-technical users.

This PRD proposes a first-run “Engine Setup” step in Host-mode onboarding that:

1. Detects whether opencode is available (and compatible)
2. If missing, offers a guided one-click install (macOS/Linux) or clear manual instructions (Windows)
3. Verifies install success and then starts opencode serve reliably, even when PATH changes don’t propagate into GUI apps

The goal is to make “fresh install → first successful task run” achievable without opening a terminal.

Problem

Today, Host mode fails with a generic spawn error when OpenWork can’t find opencode.

• Users don’t know what PATH means.
• Users don’t know where to install OpenCode.
• Even if we run an installer that modifies shell rc files, GUI apps won’t automatically inherit that updated PATH (macOS in particular).

This conflicts with OpenWork’s success metric: < 5 minutes to first successful task on fresh install.

Goals

• Detect missing OpenCode engine before the user hits “Start”.
• Provide a safe, guided install flow with explicit consent.
• Show clear progress + logs (download, unpack, verification).
• Make the engine start reliably after install (avoid “it’s installed but OpenWork can’t find it”).
• Keep parity with OpenCode primitives: still run opencode serve.

Non-goals

• Bundling opencode into OpenWork releases (possible future work).
• Implementing an auto-updater for opencode (future).
• Supporting fully offline installs (we can provide guidance, but not guarantee).

Current Architecture (Constraints)

• Tauri backend starts engine by spawning opencode serve ….
• UI connects using @opencode-ai/sdk/v2/client.
• The Tauri app is a GUI process; shell rc changes won’t necessarily affect it.

Proposed UX

Where this lives

Host onboarding adds a step after folder selection:

• Engine Setup
  • Status: Checking… / Missing / Installing… / Installed
  • Primary action: Install OpenCode (if missing)
  • Secondary: View manual install instructions
  • Tertiary: “I already installed it” → re-check

Flow A — opencode already available

1. Engine Setup runs a check.
2. If opencode is found and compatible:
   • Show “OpenCode found: vX.Y.Z”
   • Continue onboarding.

Flow B — opencode missing

1. Engine Setup detects opencode cannot be executed.
2. Show:
   • Explanation: “OpenWork needs OpenCode installed to run tasks locally.”
   • What it will do: “Download and install the OpenCode CLI to your user directory.”
   • A clear consent affordance.

Buttons

• Primary: Install OpenCode
• Secondary: Manual install
• Secondary: Retry check

Flow C — Guided install succeeds

1. OpenWork runs the installer.
2. UI streams installer output in a collapsible log drawer.
3. After completion:
   • OpenWork re-checks the engine.
   • If found, enables Start Engine.

Flow D — Guided install fails

1. UI shows “Install failed” with:
   • short reason (first stderr line)
   • “Copy logs”
   • “Manual install” instructions
   • “Retry”

Flow E — Installed but not on PATH

This is common if installation adds ~/.opencode/bin to shell rc files.

OpenWork should:

• Search known install locations (see “Engine discovery”) and use an absolute path to run opencode.
• If found outside PATH, show:
  • “OpenCode installed at ~/.opencode/bin/opencode”
  • Optional action: “Add to PATH” (manual instructions; don’t silently edit dotfiles).

Proposed Technical Approach (No Implementation Yet)

1) Engine discovery (“doctor”)

Add a Tauri command to check engine availability and return structured info:

• inPath: boolean
• resolvedPath: string | null
• version: string | null
• supportsServe: boolean
• notes: string[]

Discovery order

1. Try opencode --version (PATH)

2. Try known paths:

   • ~/.opencode/bin/opencode (matches upstream install script)
   • /opt/homebrew/bin/opencode (Homebrew Apple Silicon)
   • /usr/local/bin/opencode (Homebrew Intel)
   • Linux common paths (/usr/bin/opencode, /usr/local/bin/opencode)
   • Windows common paths (TBD)

3. If opencode is found, validate serve support:

   • opencode serve --help (exit code 0)

2) Guided install

Recommended approach (macOS/Linux): run the upstream install script with explicit consent.

Candidate URLs:

• https://opencode.ai/install (if this is the canonical stable redirect)
• https://raw.githubusercontent.com/opencode-ai/opencode/refs/heads/main/install (as documented upstream)

Execution strategy (conceptual):

• Run via bash -lc "curl -fsSL <url> | bash"
• Capture stdout/stderr and stream to the UI
• Allow choosing a pinned version (advanced): VERSION=x.y.z

Important: the install script currently writes to ~/.opencode/bin and may edit shell rc files to add PATH. OpenWork must not rely on that PATH change.

Windows: do not attempt curl | bash.

Options:

• Manual instructions only (v0)
• Or a native PowerShell installer (future) that downloads a release asset and stores it under %LOCALAPPDATA%\\OpenCode\\bin and uses that absolute path

3) Engine start should accept a resolved path

Instead of always Command::new("opencode"), engine start should prefer a resolved path from discovery.

This avoids the “installed but not on PATH” trap and improves reliability on macOS.

4) Permissions + Safety

Running an installer is sensitive.

Requirements:

• No silent remote code execution.
• Show the exact command that will run.
• Provide a “View script” action (fetch and display) before install.
• Clear opt-out path (manual install instructions).

5) Telemetry / Diagnostics (Optional)

Local-only diagnostics artifact:

• engine discovery result
• installer logs
• final engine start result

Exportable by the user to include in bug reports.

Manual install instructions (UI copy)

OpenWork should show OS-specific instructions with copy buttons.

Example:

• macOS (Homebrew): brew install opencode-ai/tap/opencode
• macOS/Linux (script): curl -fsSL https://opencode.ai/install | bash
• Linux (script fallback): curl -fsSL https://raw.githubusercontent.com/opencode-ai/opencode/refs/heads/main/install | bash

Acceptance Criteria

• Fresh machine with OpenWork installed but no opencode:
  • User can complete guided install (macOS/Linux) without terminal.
  • OpenWork verifies engine availability and can start Host mode.
• If guided install fails:
  • User sees a clear error, can copy logs, and sees manual instructions.
• If opencode is installed outside PATH:
  • OpenWork still finds and runs it via absolute path.

Open Questions

• What is the minimum supported OpenCode server version for this OpenWork release?
• Is https://opencode.ai/install the canonical stable installer URL we want to bless?
• For Windows, do we want a v0 “manual only” stance, or a PowerShell installer?
• Should OpenWork ever modify shell rc files, or only provide instructions?