# AGENTS.md - Desktop App Guidelines

Thin Electron shell hosting the fullstack server app.

## Tech Stack

> **⚠️ This project uses Bun as the package manager. Runtime is Electron (Node.js). Never use `npm`, `npx`, `yarn`, or `pnpm`.**

- **Type**: Electron desktop shell
- **Design**: Server-driven desktop (thin native window hosting web app)
- **Runtime**: Electron (Main/Renderer) + Sidecar server binary (Bun-compiled)
- **Build Tool**: electron-vite (Vite-based, handles main + preload builds)
- **Packager**: electron-builder (installers, signing, auto-update)
- **Orchestration**: Turborepo

## Architecture

- **Server-driven design**: The desktop app is a "thin" native shell. It does not contain UI or business logic; it opens a BrowserWindow pointing to the `apps/server` TanStack Start application.
- **Dev mode**: Opens a BrowserWindow pointing to `localhost:3000`. Requires `apps/server` to be running separately (Turbo handles this).
- **Production mode**: Spawns a compiled server binary (from `resources/`) as a sidecar process, waits for readiness, then loads its URL.

## Commands

```bash
bun dev                    # electron-vite dev (requires server dev running)
bun build                  # electron-vite build (main + preload)
bun dist                   # Build + package for current platform
bun dist:linux             # Build + package for Linux
bun dist:mac               # Build + package for macOS
bun dist:win               # Build + package for Windows
bun fix                    # Biome auto-fix
bun typecheck              # TypeScript check
```

## Directory Structure

```
.
├── src/
│   ├── main/
│   │   └── index.ts       # Main process (server lifecycle + BrowserWindow)
│   └── preload/
│       └── index.ts       # Preload script (security isolation)
├── resources/             # Sidecar binaries (gitignored, copied from server build)
├── out/                   # electron-vite build output (gitignored)
├── electron.vite.config.ts
├── electron-builder.yml   # Packaging configuration
├── package.json
├── turbo.json
└── AGENTS.md
```

## Development Workflow

1. **Start server**: `bun dev` in `apps/server` (or use root `bun dev` via Turbo).
2. **Start desktop**: `bun dev` in `apps/desktop`.
3. **Connection**: Main process polls `localhost:3000` until responsive, then opens BrowserWindow.

## Production Build Workflow

From monorepo root, run `bun dist` to execute the full pipeline automatically (via Turbo task dependencies):

1. **Build server**: `apps/server` → `vite build` → `.output/`
2. **Compile server**: `apps/server` → `bun compile.ts` → `out/server-{platform}`
3. **Package desktop**: `apps/desktop` → `electron-vite build` + `electron-builder` → distributable

The `electron-builder.yml` `extraResources` config reads binaries directly from `../server/out/`, no manual copy needed.

To build for a specific platform explicitly, use `bun dist:linux` / `bun dist:mac` / `bun dist:win` in `apps/desktop`.

## Critical Rules

**DO:**
- Use arrow functions for all utility functions.
- Keep the desktop app as a thin shell — no UI or business logic.
- Use `catalog:` for all dependency versions in `package.json`.

**DON'T:**
- Use `npm`, `npx`, `yarn`, or `pnpm`. Use `bun` for package management.
- Include UI components or business logic in the desktop app.
- Use `as any` or `@ts-ignore`.