# 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). Always use `bun run <script>` (not `bun <script>`) to avoid conflicts with Bun built-in subcommands. 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 run dev                    # electron-vite dev (requires server dev running)
bun run build                  # electron-vite build (main + preload)
bun run dist                   # Build + package for current platform
bun run dist:linux             # Build + package for Linux (x64 + arm64)
bun run dist:linux:x64         # Build + package for Linux x64
bun run dist:linux:arm64       # Build + package for Linux arm64
bun run dist:mac               # Build + package for macOS (arm64 + x64)
bun run dist:mac:arm64         # Build + package for macOS arm64
bun run dist:mac:x64           # Build + package for macOS x64
bun run dist:win               # Build + package for Windows x64
bun run fix                    # Biome auto-fix
bun run 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 run dev` in `apps/server` (or use root `bun run dev` via Turbo).
2. **Start desktop**: `bun run dev` in `apps/desktop`.
3. **Connection**: Main process polls `localhost:3000` until responsive, then opens BrowserWindow.

## Production Build Workflow

From monorepo root, run `bun run 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 --target ...` → `out/server-{os}-{arch}`
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 run dist:linux` / `bun run dist:mac` / `bun run dist:win` in `apps/desktop`.
For single-arch output, use `bun run dist:linux:x64`, `bun run dist:linux:arm64`, `bun run dist:mac:x64`, or `bun run dist:mac:arm64`.

## Development Principles

> **These principles apply to ALL code changes. Agents MUST follow them on every task.**

1. **No backward compatibility** — This project is in rapid iteration. Always use the latest API and patterns. Never keep deprecated code paths or old API fallbacks.
2. **Always sync documentation** — When code changes, immediately update all related documentation (`AGENTS.md`, `README.md`, inline code examples). Code and docs must never drift apart.
3. **Forward-only migration** — When upgrading dependencies, fully adopt the new API. Don't mix old and new patterns.

## 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`.
- Leave docs out of sync with code changes.