# PawFlow Relay Desktop

Electron desktop manager for standalone PawFlow client relays.

PawCode and the VS Code extension are PawFlow clients only. This desktop app owns client-side relay lifecycle on a user machine:

- register PawFlow servers;
- login through the configured server/private gateway;
- define local workspace shares;
- start and stop relay processes;
- view relay logs.

## Run From Source

```bash
cd pawflow-relay-desktop
npm install
npm run prepare-runtime
npm start
```

On Windows, do not run `npm start` directly from a `\\wsl$\\...` UNC path:
`cmd.exe` cannot use UNC paths as its current directory, and npm package
scripts go through `cmd.exe`. Use the wrapper instead:

```powershell
.\start-windows.ps1 -Install
```

or, after dependencies are installed:

```powershell
.\start-windows.ps1
```

The wrapper uses WSL cleanup for broken UNC `node_modules` directories and
`cmd.exe pushd` to map the UNC path to a temporary drive letter before starting
Electron.

When Docker Desktop is available only through WSL, the app first tries the
Windows `docker` CLI and then falls back to `wsl.exe docker`. Set the distro
explicitly when needed:

```powershell
$env:PAWFLOW_RELAY_WSL_DISTRO = "Ubuntu-24.04"
.\start-windows.ps1
```

## Portable Runtime

`npm run prepare-runtime` creates `pawflow-relay-desktop/runtime/` with the
Python relay package, PawCode login helpers, relay tool scripts, and PawFlow SDK
shim required by the Docker relay. For a copyable dev bundle, run:

```bash
npm run package:portable
```

This writes `dist/pawflow-relay-desktop/`. Copy that directory to a Windows-local
path, then run:

```powershell
.\start-windows.ps1 -Install
```

A copied desktop directory must contain:

```text
runtime/tools/
runtime/pawflow_relay/
runtime/pawflow_cli/
runtime/docker/pawflow_sdk/pawflow.py
```

The app calls the Python module from `runtime/` first, then falls back to the
repository root for source development. On Windows it starts `python` directly
instead of the `py.exe` launcher so the relay does not keep an extra launcher
process alive. Override the Python executable when needed:

```bash
PAWFLOW_RELAY_PYTHON=/path/to/python npm start
```

## Native Installers

Relay Desktop can be packaged as a user-facing app with an embedded relay
binary. The packaged app no longer requires Python to start relays or manage
local server/workspace profiles; it launches `runtime/bin/pawflow-relay` (or
`pawflow-relay.exe` on Windows) and falls back to `python -m pawflow_relay` only
for source development.

Build the relay binary with PyInstaller, then create an installer for the host
platform:

```bash
cd pawflow-relay-desktop
python -m pip install pyinstaller
npm install
npm run dist:linux   # AppImage + deb
npm run dist:win     # NSIS exe + zip, from Windows
npm run dist:mac     # dmg + zip, from macOS
```

On Windows, `electron-builder` extracts a `winCodeSign` helper archive that
contains symlinks. If extraction fails with `Cannot create symbolic link`, enable
Windows Developer Mode or run PowerShell as Administrator, clear the broken
cache, then rebuild:

```powershell
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\electron-builder\Cache\winCodeSign" -ErrorAction SilentlyContinue
$env:CSC_IDENTITY_AUTO_DISCOVERY = "false"
npm run dist:win
```

`npm run dist` runs `prepare-runtime`, builds the relay executable into
`runtime/bin/`, then invokes `electron-builder`. Docker is still an external
runtime dependency; the app detects Docker availability and reports startup or
permission issues in the UI.

## Shared State

Relay Desktop uses the same local state as the standalone CLI:

- Linux/macOS: `~/.pawflow/relay/`
- Windows: `%APPDATA%\\PawFlow\\relay\\`
- Override: `PAWFLOW_RELAY_HOME=/custom/path`

That means a server/workspace created with `pawflow-relay` appears in the desktop app, and vice versa.

## Current Scope

This is the first desktop management slice. It intentionally does not replace the webchat resource panel for server relays. Server relays remain a server/webchat resource concern; this app manages client relays on the user's machine.
