claudetools/.claude/skills/gururmm-build/SKILL.md

name, description

name

description

gururmm-build

Build and pre-merge verification for the GuruRMM codebase (agent/server/dashboard). Encodes the fleet's build model so every dev/machine builds the SAME way Mike does: merging to main is the build+deploy trigger (no separate build step), so verify locally first. Wraps the cargo/npm commands the server-side pipeline runs, with the compile-gate gotcha baked in (Linux-gated agent code can't be verified by Windows cargo check; server needs SQLX_OFFLINE + a fresh .sqlx cache; dashboard uses npm install not ci). Triggers: build the rmm agent/server/dashboard, verify the linux build, gururmm build, pre-merge check, will this compile, sqlx prepare, migration collision, promote dashboard, what does merging to main do.

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

# 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:

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:

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.