# Local Development Setup

> **Architectural Foundation:** [Node.js](https://nodejs.org/) · [pnpm](https://pnpm.io/) · [Turborepo](https://turbo.build/repo)
>
> **Description:** Local development setup guide covering prerequisites (Node.js v20+, pnpm v8), workspace installation, and Turborepo-orchestrated development and build scripts.

## 🚀 Getting Started

### Prerequisites

Ensure your local environment matches the following versions to avoid compatibility issues:

* **[Node.js](https://nodejs.org/)**: `v20+` (tested with `v24.11.1`) — required for the `--import tsx` flag used by the desktop prebuild script
* **[pnpm](https://pnpm.io/)**: `v8.15.6`
  (Enforced via the `packageManager` field in `package.json`)

### Installation

Install all dependencies from the **root directory**:

```bash
pnpm install
```

## 🛠 Usage & Scripts

This repository uses **[Turborepo](https://turbo.build/repo)** to orchestrate tasks efficiently. All commands are executed from the root.

### Development

| Command              | Description                                                                        |
| -------------------- | ---------------------------------------------------------------------------------- |
| `pnpm dev`           | Start **all applications** (`web` and `docs-dev`) in parallel                      |
| `pnpm dev:web`       | Start only the **Main Web App** (strictly at `http://localhost:5173`)               |
| `pnpm dev:landing`   | Start the **Public Landing App** (strictly at `http://localhost:3000`)              |
| `pnpm dev:docs-dev`  | Start **[VitePress](https://vitepress.dev/)** for documentation development (strictly at `http://localhost:6060`) |
| `pnpm dev:desktop`   | Start the **Web App + Electron** in parallel for desktop development               |

> [!NOTE]
> **Port Topology**: `electron-vite` dynamically allocates a background port (usually `5174`) for its internal renderer shell during `pnpm dev:desktop`. We strictly isolate `web` (`5173`) and `landing` (`3000`) onto separate port ranges to prevent race conditions during parallel execution.

### Building & Quality

| Command               | Description                                             |
| --------------------- | ------------------------------------------------------- |
| `pnpm build`          | Build all apps and packages using Turbo cache           |
| `pnpm build:web`      | Build only the web application                          |
| `pnpm build:landing`  | Build only the landing page                             |
| `pnpm build:docs-dev` | Build only the docs-dev application                     |
| `pnpm build:desktop`  | Build the web app, then compile the Electron app        |
| `pnpm test`           | Run unit tests ([Vitest](https://vitest.dev/)) across all packages             |
| `pnpm lint`           | Run [ESLint](https://eslint.org/) across the workspace                         |
| `pnpm format`         | Format code using [Prettier](https://prettier.io/)                              |

### 🚀 Desktop Packaging & Distribution

To package the application into a production-ready installer, use the following commands from the **root directory**:

| Command                | Platform    | Output Artifact                            |
| ---------------------- | ----------- | ------------------------------------------ |
| `pnpm package:desktop` | Current OS  | Detects host OS and builds accordingly     |
| `pnpm package:mac`     | macOS       | `.dmg` and `.zip` (supports x64 & arm64)   |
| `pnpm package:win`     | Windows     | `.exe` (NSIS Installer)                    |
| `pnpm package:linux`   | Linux       | `.AppImage`                                |

> [!IMPORTANT]
> **Build Sequence**: All `package:*` commands execute the following pipeline automatically:
>
> 1. **`turbo run build --filter=web`** — Compiles the React SPA into `apps/web/dist/`.
> 2. **`prebuild` hook** — Runs `node --import tsx scripts/copy-web-dist.ts`, which copies `apps/web/dist/` → `apps/desktop/web-dist/`.
> 3. **[`electron-builder`](https://www.electron.build/)** — Bundles `web-dist/` into the packaged app via the `files` and `extraResources` blocks in `electron-builder.yml`.
>
> You do not need to run these steps manually — they are chained via npm scripts.

> [!WARNING]
> **macOS Code Signing**: To build a distributable macOS app with Auto-Update support, you **must** have an Apple Developer Certificate and provide `CSC_LINK` and `CSC_KEY_PASSWORD` in your environment. Without code signing, macOS Gatekeeper will block the app and auto-updates will fail. See the Desktop documentation for details.

> [!NOTE]
> **Cross-Compilation**: It is highly recommended to build for Windows on a Windows machine and for macOS on a Mac. Cross-compilation (e.g., building `.dmg` on Linux) may fail due to platform-specific toolchain dependencies. Use a CI matrix strategy (e.g., GitHub Actions with `runs-on: [macos-latest, windows-latest, ubuntu-latest]`) for multi-platform releases.