---
name: gururmm-build
description: "Build + pre-merge verification for GuruRMM (agent/server/dashboard). Merge-to-main IS the build+deploy trigger, so verify locally first. Triggers: build the rmm agent/server/dashboard, gururmm build, pre-merge check, will this compile, sqlx prepare, promote dashboard."
---

# gururmm-build — Build & pre-merge verification for GuruRMM

One skill so the whole fleet builds GuruRMM the same way. The actual build+deploy happens
server-side on a push to `main` (Gitea webhook → `webhook-handler.py` on `172.16.3.30`); this
skill is the **local pre-merge verification** layer plus the mental model, so nobody merges code
that fails the server build.

The human-facing companion doc lives in the project: `projects/msp-tools/guru-rmm/docs/BUILD.md`.
The server-side pipeline source of truth is `projects/msp-tools/guru-rmm/deploy/build-pipeline/README.md`.

## The one rule

**Merging to `main` is the build-and-deploy trigger. There is no separate build step.** New
agent/server/dashboard binaries land on **beta** first; prod promotion is deliberate and separate.
So: verify locally before you merge, and after merge watch the relevant build log on `.30`.

## Commands

```bash
# Verify a component compiles the way the server will (run from anywhere in the fleet)
bash .claude/skills/gururmm-build/scripts/verify.sh server      # SQLX_OFFLINE cargo build + .sqlx freshness check
bash .claude/skills/gururmm-build/scripts/verify.sh agent       # cargo build (warns about the compile gate per-OS)
bash .claude/skills/gururmm-build/scripts/verify.sh dashboard   # npm install + npm run build
bash .claude/skills/gururmm-build/scripts/verify.sh all         # all three

# Faster: cargo check instead of a full release build (Rust components only)
bash .claude/skills/gururmm-build/scripts/verify.sh server --check
bash .claude/skills/gururmm-build/scripts/verify.sh agent --check

# Check for a migration number collision before you name/merge a new migration
bash .claude/skills/gururmm-build/scripts/verify.sh migrations
```

The script auto-locates the guru-rmm checkout (the `projects/msp-tools/guru-rmm` submodule),
detects the host OS, applies the right toolchain/env, and logs real failures to `errorlog.md`.

## The compile gate (why Windows cargo check is not enough)

The agent compiles across OSes and toolchains; **each OS gates only its own platform code**:

- **Linux-gated agent code** (`#[cfg(target_os = "linux")]`, e.g. `is_docker_container()` in
  `agent/src/updater/mod.rs`) is only compiled by the **Linux** agent build. You cannot verify it
  with cargo on Windows — `openssl-sys` won't cross-build there. `verify.sh agent` warns when you're
  on Windows and the change may be Linux-gated. To truly gate it, build on Linux or watch the
  post-merge `/var/log/gururmm-build-linux.log` on `.30`.
- **Windows-only code** — MSI (`installer/`, WiX), tray (`tray/`), legacy (Rust 1.77) + x86 variants
  — is only built on the Beast/Pluto Windows hosts; a Linux/macOS box can't gate it.

Rule: **build agent changes on the OS family they target.**

## Server + sqlx (the other common merge-breaker)

`build-server.sh` builds with `SQLX_OFFLINE=true` against the committed `server/.sqlx` cache. If you
changed SQL queries or added a migration and did **not** refresh the cache, the server build fails:

```bash
cd server && cargo sqlx prepare         # needs a reachable DB; regenerates server/.sqlx
git add server/.sqlx && git commit -m "chore: refresh sqlx offline cache"
```

`verify.sh server` flags when `server/` query code changed but `server/.sqlx` was not also touched.

## Migrations

Numbered `NNN_description.sql`, applied on server deploy. Keep them idempotent
(`CREATE INDEX IF NOT EXISTS`). **Number collisions across branches are real** — if two branches
both add `060_*`, the second to merge must be renumbered. `verify.sh migrations` reports the highest
migration on `main` and any duplicate numbers so you pick the next free one.

## After merge

Build logs on `.30`: `gururmm-build.log` (shared/version bump), `-linux`, `-windows`, `-server`,
`-dashboard`. Server deploy auto-rolls-back if the new binary won't start. Agents + dashboard land
on **beta**. Promote the dashboard to prod deliberately:

```bash
sudo /opt/gururmm/promote-dashboard.sh            # dry-run delta
sudo /opt/gururmm/promote-dashboard.sh --confirm  # promote (backs up prod)
sudo /opt/gururmm/promote-dashboard.sh --rollback # undo last promotion
```

## Notes

- This skill does **not** trigger the production build — that's the webhook on merge to `main`. It
  verifies locally and documents the model.
- A full `cargo build --release` for agent/server is slow (minutes); use `--check` for a fast gate
  and the release build only when you need the real artifact.
- Detail: `projects/msp-tools/guru-rmm/docs/BUILD.md` and `deploy/build-pipeline/README.md`.
