--- name: GuruRMM project state — dev principles, webhook docs guard, pending setup description: GuruRMM project state — dev principles (every feature full-stack: backend+API+UI+docs+scalability; product works without AI; FEATURE_ROADMAP update is part of definition-of-done), the webhook docs-only build guard (SPEC-020 Phase 0; repo copy of webhook-handler.py is STALE — don't redeploy), and the still-pending Mac install-hooks.sh setup on Mikes-MacBook-Air. type: project --- Rules: [[feedback_gururmm]]. Technical reference: [[reference_gururmm]]. Canonical principles doc: `projects/msp-tools/guru-rmm/docs/DESIGN.md` (this file is the in-context summary). --- ## Dev principles (created 2026-04-29; authority: Mike Swanson) ### Holistic feature development (MANDATORY) Every GuruRMM feature ships with the complete stack: 1. **Backend / agent logic** — core capability 2. **API endpoints** — control + monitoring 3. **UI / UX** — dashboard configuration, status display, management 4. **Documentation** — user guides and operational docs 5. **Scalability** — architected for future expansion **Example — Network Discovery Node** is complete when: agent-side scanning (ICMP/ARP/SNMP), server-side data + API, dashboard for designating the discovery node + viewing discovered devices + configuring scan schedules + IP ranges/exclusions, status indicators, future-proof data model supporting multiple discovery methods. **Features shipped without their UI / configuration interfaces are incomplete and will be rejected.** Same standard for backend-only implementations, features requiring API expertise to configure, and designs that paint into architectural corners. ### Living roadmap (MANDATORY) `projects/msp-tools/guru-rmm/docs/FEATURE_ROADMAP.md` is the single living record. `[ ]` = planned, `[x]` = shipped (annotate with date). - **Before building:** read the feature's roadmap entry for intent/scope. New work that isn't on the roadmap gets an entry first. - **When shipping or modifying a feature:** update its roadmap entry in the SAME change — flip `[ ]` → `[x]` with a date, or revise/add the item. **Code change without the matching roadmap update is incomplete** (same standard as shipping without UI). - **Don't over-claim:** if only part is done, keep `[ ]` and annotate the partial scope (e.g. "TCP probing shipped; ICMP/ARP/SNMP pending") rather than flipping. - `/rmm-audit`'s roadmap pass is the **backstop** that reconciles drift — not the primary maintainer. Dev work keeps the roadmap honest; the audit catches what slipped. ### AI-optional operation GuruRMM must be fully functional **without** requiring AI agents to operate. All functionality accessible via the traditional dashboard / API; configuration via standard interfaces; usable by MSP techs with zero AI/ML knowledge; deterministic, reliable operation for production. AI features (agentic analysis, agentic command routing) are **enhancements** — users choose whether to enable them. Production stability over experimental features. ### Planning questions for every feature - How does an admin configure this in the dashboard? - What does the status display look like? - How do we expand this in v2/v3? - Does this work if AI services are unavailable? --- ## Webhook docs-only build guard (SPEC-020 Phase 0) The GuruRMM build webhook (`gururmm-webhook.service` → `/opt/gururmm/webhook-handler.py` on 172.16.3.30) has a **docs-only build guard** as of 2026-05-30: a push whose every changed file matches `docs/`, `*.md`, `.claude/`, `session-logs/`, `LICENSE`, or `.gitignore` returns `Docs-only change -- build skipped` and triggers no build. **Fail-safe toward building** — no file list or any buildable file → build runs. Detection uses the Gitea push payload's per-commit `added`/`removed`/`modified` lists (`is_docs_only` / `NON_BUILDABLE`). Verified live (docs push skipped, no build locks, `last-built-commit` unchanged). Backup: `/opt/gururmm/webhook-handler.py.bak-20260530-guard`. This is **Phase 0** (interim). The full fix migrates RMM CI to Gitea Actions with native `paths-ignore`, matching GuruConnect (ADR-002) — see [[reference_gitea_internal]]. **Caveat about `webhook-handler.py` specifically:** the repo copy `scripts/webhook-handler.py` is STALE (109 lines vs the deployed 206 — predates the split-build refactor) and does NOT contain the guard. Do NOT redeploy it over the host copy; the host is the source of truth until SPEC-020 lands. (The other 6 build scripts auto-sync from `deploy/build-pipeline/` per [[reference_gururmm]] §pipeline-vendoring — this caveat is `webhook-handler.py`-only.) --- ## Pending setup — Mikes-MacBook-Air `install-hooks.sh` **STATUS:** Genuinely still pending as of 2026-05-27. Verified: gururmm submodule is initialized on the Mac but only default `.sample` hooks are present. **Action (do this before any gururmm dev on the Mac):** ```bash cd /Users/azcomputerguru/ClaudeTools/projects/msp-tools/guru-rmm git pull bash scripts/install-hooks.sh ``` **What it does:** sets `core.hooksPath = scripts/hooks/` (activates the pre-commit CRLF check), `core.autocrlf=false`, `core.eol=lf` (locally and globally) — prevents sqlx migration checksum drift (root cause: CRLF vs LF sha384 mismatch from Windows commits). **Why:** the gururmm build server once refused to start after a rebuild because migration file hashes differed between what was stored in `_sqlx_migrations` and the current files. Fixed with `.gitattributes` + per-machine git config. This step applies the git config side. macOS defaults to LF — low-risk; mainly activates the pre-commit guard. **When complete:** delete this section from this memory file (or remove the file entirely if no other RMM project state has been added).