azcomputerguru/claudetools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

sync: auto-sync from GURU-5070 at 2026-05-24 13:57:13

Browse Source 
Author: Mike Swanson
Machine: GURU-5070
Timestamp: 2026-05-24 13:57:13
This commit is contained in:
Mike Swanson
2026-05-24 13:57:16 -07:00
parent bd9f8a12f9
commit 435e921300
3 changed files with 375 additions and 986 deletions
Download Patch File Download Diff File Expand all files Collapse all files

210
.claude/machines/pluto.md Normal file
View File

@@ -0,0 +1,210 @@
# Machine: Pluto (Claude-Builder)
**Hostname:** Pluto / Claude-Builder
**Last Updated:** 2026-05-24
---
## Identity
Pluto is the **Windows build VM** for GuruRMM. It is the only machine in the fleet
that produces Windows agent binaries and the WiX MSI installer. It is NOT a
general-purpose workstation — it has no Claude Code, no vault, no coord API access.
Its sole function is to run `cargo build` for Windows targets when `build-windows.sh`
SSHes in.
---
## Hardware & Location
| Spec | Value |
|------|-------|
| VM name | Claude-Builder (virsh domain on Jupiter) |
| Host | Jupiter — Unraid primary, IP 172.16.3.20 |
| VM IP | 172.16.3.36 |
| OS | Windows Server 2019 (Standard) |
| SSH user | Administrator |
| SSH port | 22 |
| SSH auth | Public key, from build server (172.16.3.30) |
Pluto is a virsh VM. If it is unreachable from 172.16.3.30 but was recently
building, check Jupiter first (`virsh list --all` on 172.16.3.20) before
assuming a crash. SSH from DESKTOP-0O8A1RL and SSH from 172.16.3.30 traverse
different network paths — one failing does not imply the other fails.
---
## Build Tools
| Tool | Path |
|------|------|
| cargo (Rust stable) | `C:\Users\Administrator\.cargo\bin\cargo.exe` |
| rustup | `C:\Users\Administrator\.cargo\bin\rustup.exe` |
| WiX 4 (MSI builder) | `C:\Users\Administrator\.dotnet\tools\wix.exe` |
| sccache | `C:\sccache\` (compiler cache, causes near-instant rebuilds when source unchanged) |
| Git | standard PATH |
**sccache note:** When agent/ has no code changes (only config bumps), sccache
makes the full 5-target cargo run complete in ~1s rather than 3–5 min. This is
expected and correct — do not interpret a fast build as a failed build.
---
## Repo
| Item | Value |
|------|-------|
| Clone path | `C:\gururmm` |
| Remote | Gitea: `https://azcomputerguru@git.azcomputerguru.com/azcomputerguru/gururmm.git` |
| Branch | main (build-windows.sh pulls latest before building) |
---
## Build Role in Pipeline
Pluto is invoked by `build-windows.sh` on the build server (172.16.3.30) via SSH.
It is called only when `agent/` has changed since the last Windows build
(`/opt/gururmm/last-built-commit-windows`).
### What Pluto does (in order):
```
1. git pull (build-windows.sh does this via SSH before cargo invocations)
2. cargo build --release --target x86_64-pc-windows-msvc → stable x64
3. cargo build --features debug-agent --target x86_64-pc-windows-msvc → debug x64
4. cargo build --release --target i686-pc-windows-msvc → stable x86
5. cargo build --release --target x86_64-pc-windows-msvc (legacy profile) → legacy x64
6. cargo build --release --target i686-pc-windows-msvc (legacy profile) → legacy x86
7. wix build (WiX 4) → GuruRMM-<version>-x64.msi
```
All five cargo invocations run sequentially on Pluto. The MSI is built after all
binaries complete.
### Output artifacts (on Pluto):
| Artifact | Pluto path |
|----------|-----------|
| Agent EXE (x64) | `C:\gururmm\target\x86_64-pc-windows-msvc\release\gururmm-agent.exe` |
| Agent EXE (x86) | `C:\gururmm\target\i686-pc-windows-msvc\release\gururmm-agent.exe` |
| Tray EXE | `C:\gururmm\target\x86_64-pc-windows-msvc\release\gururmm-tray.exe` |
| MSI | `C:\gururmm\target\wix\GuruRMM-<version>-x64.msi` |
`build-windows.sh` SCPs these from Pluto to the build server's distribution
directory (`/var/www/gururmm/downloads/`) after the build completes.
---
## Connection from Build Server
```bash
# From 172.16.3.30 (build server), as guru
ssh -o StrictHostKeyChecking=yes \
-o UserKnownHostsFile=/opt/gururmm/pluto_known_hosts \
Administrator@172.16.3.36
```
The known-hosts file at `/opt/gururmm/pluto_known_hosts` contains three pinned
keys (RSA, ECDSA, ED25519) for 172.16.3.36. **Never use StrictHostKeyChecking=no
for Pluto** — it would accept a MITM and inject malicious binaries into the
build artifacts.
To update the pinned keys (e.g., after OS reinstall):
```bash
ssh-keyscan 172.16.3.36 > /opt/gururmm/pluto_known_hosts
```
---
## Pipeline Context
| Script | Role |
|--------|------|
| `/opt/gururmm/webhook-handler.py` | Receives Gitea webhook on 172.16.3.30:9000, forks build threads |
| `/opt/gururmm/build-shared.sh` | Version bump + repo sync; runs once per trigger |
| `/opt/gururmm/build-linux.sh` | Linux cargo build; independent of Pluto |
| `/opt/gururmm/build-windows.sh` | Invokes Pluto via SSH; handles change gate + artifact copy |
| `/opt/gururmm/build-mac.sh` | Stub; no Mac build machine configured |
`build-linux.sh` and `build-windows.sh` run in parallel threads from
`webhook-handler.py` after `build-shared.sh` succeeds.
### Build logs on 172.16.3.30:
| Log | Content |
|-----|---------|
| `/var/log/gururmm-build-linux.log` | Linux build output |
| `/var/log/gururmm-build-windows.log` | Windows build + Pluto SSH output (prefixed `[PLUTO]`) |
| `/var/log/gururmm-build-mac.log` | Mac stub (minimal) |
### Change tracking:
| File | Tracks |
|------|--------|
| `/opt/gururmm/last-built-commit-linux` | Last SHA successfully built on Linux |
| `/opt/gururmm/last-built-commit-windows` | Last SHA successfully built on Windows (Pluto) |
| `/opt/gururmm/last-built-commit-mac` | Last SHA successfully built on Mac (stub) |
---
## Distribution Directory (on 172.16.3.30)
Active artifacts served via nginx:
```
/var/www/gururmm/downloads/
windows/
amd64/
GuruRMM-<version>-x64.msi
gururmm-agent-<version>.exe
gururmm-tray-<version>.exe (latest 2 versions kept)
x86/
gururmm-agent-<version>.exe
```
The legacy path `/opt/gururmm/updates/windows/amd64/` contains only old artifacts
from before the pipeline split (last modified ~Feb 2026). It is NOT the active
distribution path — do not check it to assess build freshness.
---
## Build Trigger Rules
A build to Pluto is only initiated when:
1. A push to `main` hits the Gitea webhook
2. `build-shared.sh` succeeds (version bump + git sync)
3. The diff between the new SHA and `last-built-commit-windows` includes changes
under `agent/` (excluding `agent/Cargo.lock`)
If only `server/`, `dashboard/`, or docs changed, Pluto is NOT contacted.
The Windows lock file (`/var/run/gururmm-build-windows.lock`) prevents concurrent
builds if a previous run is still active.
---
## Capabilities
- [x] Windows cargo builds (stable x64, debug x64, stable x86, legacy x64, legacy x86)
- [x] WiX 4 MSI packaging
- [x] sccache (compiler-level cache, C:\sccache)
- [x] SSH access from 172.16.3.30 (key auth, pinned known-hosts)
- [x] Git (pulls gururmm repo from Gitea)
- [ ] Claude Code (not installed)
- [ ] SOPS vault (not installed)
- [ ] Coord API access (not installed)
- [ ] Mac cross-compilation (not configured)
---
## Notes
- **Do not SSH to Pluto manually to trigger builds.** All builds go through the
Gitea webhook pipeline. Manual SSH is for diagnostics only.
- **If Pluto appears unreachable from DESKTOP:** Verify from 172.16.3.30 first.
Different network paths. DESKTOP is not on the same LAN segment as Pluto.
- **sccache makes short work of rebuild-only pushes.** A 1-second Windows build
is normal when agent/ source hasn't changed since the last successful build.
- **Build history:** Pluto has been building GuruRMM Windows agents since at least
early 2026. The MSI + EXE artifacts in `/var/www/gururmm/downloads/` are
authoritative freshness indicators — check their timestamps, not the legacy
`/opt/gururmm/updates/` path.

180
.claude/skills/rmm-audit/SKILL.md
View File

@@ -1,14 +1,16 @@
---
name: rmm-audit
description: |
Periodic end-to-end verification of the GuruRMM codebase. Runs 5 parallel audit
passes: (1) API/route inventory cross-reference, (2) UI coverage and gap update,
(3) Rust code quality and standards compliance, (4) TypeScript/frontend quality,
(5) security and data integrity. Produces a timestamped audit report and updates
the living docs (UI_GAPS.md, FEATURE_ROADMAP.md). Takes 10-20 minutes.
Periodic end-to-end verification of the GuruRMM codebase and build infrastructure.
Runs 5 parallel audit passes: (1) API/route inventory cross-reference, (2) UI
coverage and gap update, (3) Rust code quality and standards compliance,
(4) TypeScript/frontend quality, (5) security and data integrity. A 6th sequential
pass audits build pipeline health (logs, artifacts, change gates, script integrity).
Produces a timestamped audit report and updates the living docs (UI_GAPS.md,
FEATURE_ROADMAP.md). Takes 10-20 minutes.
Invoke explicitly only — no auto-trigger. Use /rmm-audit for a full audit.
Optional arg: --pass=<name> to run a single pass (api, ui, rust, ts, security).
Optional arg: --pass=<name> to run a single pass (api, ui, rust, ts, security, pipeline).
---
# GuruRMM End-to-End Audit
@@ -22,14 +24,16 @@ report file and living docs are updated. No code is changed.
```
Phase 0: Context load (coordinator reads key files)
Phase 1: Spawn 4 parallel audit agents
Phase 2: Collect findings, aggregate, score
Phase 3: Write report + update living docs
Phase 4: Present summary to user
Phase 1: Spawn 5 parallel audit agents (codebase passes)
Phase 2: Run build pipeline audit (sequential — requires SSH to build server)
Phase 3: Collect findings, aggregate, score
Phase 4: Write report + update living docs
Phase 5: Present summary to user
```
The audit is orchestrated here (Claude coordinator). All heavy passes run in
parallel subagents. Each agent returns structured findings; the coordinator
The audit is orchestrated here (Claude coordinator). All codebase passes run in
parallel subagents. The build pipeline pass runs sequentially after (it touches
live server state via SSH). Each agent returns structured findings; the coordinator
aggregates and writes the final report.
---
@@ -214,9 +218,128 @@ Return structured findings with file:line references.
---
## Phase 2: Aggregating Findings
---
Collect all four agents' outputs. Classify each finding:
### Agent E — Build Pipeline Health
**Goal:** Verify the build/deploy infrastructure is functioning correctly and producing
fresh, trustworthy artifacts. This pass catches issues invisible to codebase-only
audits: log rot, stale artifacts, dead pipeline paths, and change gate failures.
**NOTE:** This agent runs sequentially (after Agents A–D complete) because it SSHes
into the live build server. It is read-only — it checks state but does not trigger builds.
**Instructions for agent:**
Connect to the build server: `ssh guru@172.16.3.30`
**1. Log integrity — check for doubling and freshness:**
```bash
# Check Windows build log — each line should appear exactly once
tail -50 /var/log/gururmm-build-windows.log
# Check Linux build log
tail -50 /var/log/gururmm-build-linux.log
```
- Lines duplicated (same content appearing twice in a row) → `[HIGH]` log doubling — double-writer bug
- Last entry timestamp > 7 days old AND recent pushes known → `[HIGH]` stale log — builds may be silently failing
- Log file missing entirely → `[CRITICAL]` — build infrastructure not initialised
- Presence of `=== PHASE:` markers → `[INFO]` phase tracking is active (expected)
**2. Artifact freshness — check distribution directory:**
```bash
ls -lht /var/www/gururmm/downloads/windows/amd64/ | head -10
ls -lht /var/www/gururmm/downloads/linux/amd64/ | head -10
```
- Newest MSI/EXE older than 14 days AND active development confirmed → `[HIGH]` artifacts stale
- Legacy path `/opt/gururmm/updates/windows/amd64/` should NOT be served (it is the old path); if a
symlink or nginx config still points there → `[HIGH]` dead artifact path still active
**3. Per-platform last-built-commit recency:**
```bash
cat /opt/gururmm/last-built-commit-linux
cat /opt/gururmm/last-built-commit-windows
cat /opt/gururmm/last-built-commit-mac
```
- SHA should be recent relative to `git log --oneline -5` in `/home/guru/gururmm`
- Linux and Windows SHAs diverging by many commits → `[MEDIUM]` platform builds out of sync
- A SHA that resolves to a commit months old while git log shows recent work → `[HIGH]` change gate stuck
**4. Stale lock files:**
```bash
ls -la /var/run/gururmm-build-*.lock 2>/dev/null
```
- Lock file present with no corresponding running process → `[HIGH]` orphaned lock, all future builds for that
platform will be blocked until manually removed
- Check: `ps aux | grep build-` — if no `build-linux.sh` / `build-windows.sh` running but lock exists, it's orphaned
**5. Script syntax validity:**
```bash
bash -n /opt/gururmm/build-shared.sh
bash -n /opt/gururmm/build-linux.sh
bash -n /opt/gururmm/build-windows.sh
bash -n /opt/gururmm/build-mac.sh
```
- Any syntax error → `[CRITICAL]` — that platform's builds will silently fail at next trigger
**6. Webhook handler health:**
```bash
curl -s http://localhost:9000/health
ps aux | grep webhook-handler
```
- `/health` returns non-200 or connection refused → `[CRITICAL]` webhook handler down
- Handler not in process list → `[CRITICAL]` handler not running
- Check handler is using the new multi-threaded version (should mention `PLATFORMS` in its source):
`grep -c PLATFORMS /opt/gururmm/webhook-handler.py`
Count of 0 → `[HIGH]` old monolithic handler still deployed
**7. Pluto known-hosts file:**
```bash
ls -la /opt/gururmm/pluto_known_hosts
wc -l /opt/gururmm/pluto_known_hosts
```
- File missing → `[CRITICAL]` Windows builds will fail (SSH strict host checking with no key file)
- File empty (0 lines) → `[CRITICAL]` same
- Confirm `build-windows.sh` references it: `grep pluto_known_hosts /opt/gururmm/build-windows.sh`
If missing → `[HIGH]` StrictHostKeyChecking=no likely, MITM risk on build artifacts
**8. Tray EXE accumulation:**
```bash
ls -lht /var/www/gururmm/downloads/windows/amd64/gururmm-tray-* 2>/dev/null | wc -l
```
- More than 3 tray EXE versions present → `[LOW]` cleanup not running (design: keep latest 2)
**9. Build compat wrapper check:**
```bash
head -5 /opt/gururmm/build-agents.sh
```
- Should begin with a deprecation warning and call to `build-shared.sh`
- If it still contains the old monolithic build logic → `[HIGH]` pipeline split not deployed
Return structured findings with source (file path + line or command output) for every finding.
---
## Phase 3: Aggregating Findings
Collect all five agents' outputs. Classify each finding:
| Severity | Meaning |
|----------|---------|
@@ -244,7 +367,7 @@ Write to: `projects/msp-tools/guru-rmm/reports/YYYY-MM-DD-rmm-audit.md`
# GuruRMM Audit Report — YYYY-MM-DD
**Auditor:** Claude (claude-sonnet-4-6)
**Passes:** API Coverage, UI Gaps, Rust Quality, TypeScript Quality, Data Integrity
**Passes:** API Coverage, UI Gaps, Rust Quality, TypeScript Quality, Data Integrity, Build Pipeline
**Previous audit:** [link to prior report if one exists, else "First audit"]
---
@@ -258,6 +381,7 @@ Write to: `projects/msp-tools/guru-rmm/reports/YYYY-MM-DD-rmm-audit.md`
| Rust Quality | N | N | N | N | N |
| TypeScript | N | N | N | N | N |
| Data Integrity | N | N | N | N | N |
| Build Pipeline | N | N | N | N | N |
| **TOTAL** | **N** | **N** | **N** | **N** | **N** |
**Requires immediate action:** [list of CRITICAL findings in one line each]
@@ -300,6 +424,13 @@ are now COMPLETE vs. still open vs. newly discovered.]
---
## Pass 6: Build Pipeline Health
[findings — log integrity, artifact freshness, change gate state, lock files, script
syntax, webhook handler health, Pluto known-hosts, tray EXE accumulation]
---
## UI_GAPS.md Delta
Items completed since last audit:
@@ -330,7 +461,7 @@ After writing the report, update `docs/UI_GAPS.md`:
---
## Phase 4: User Summary
## Phase 5: User Summary
Present a concise summary to the user:
@@ -341,6 +472,7 @@ CRITICAL (N): [one-line each]
HIGH (N): [one-line each]
MEDIUM (N): Batched in report.
Pipeline: [one-line status — e.g. "all green" or highest-severity finding]
UI_GAPS.md: N items marked complete, N new gaps added.
Recommended first action: [the single highest-priority finding]
@@ -402,3 +534,19 @@ Then ask: "Want me to start on any of these findings?"
| UI gaps tracker | `projects/msp-tools/guru-rmm/docs/UI_GAPS.md` |
| Architecture decisions | `projects/msp-tools/guru-rmm/docs/ARCHITECTURE_DECISIONS.md` |
| Past audit reports | `projects/msp-tools/guru-rmm/reports/` |
### Build Pipeline (on 172.16.3.30)
| Area | Path |
|------|------|
| Webhook handler | `/opt/gururmm/webhook-handler.py` |
| Shared build script | `/opt/gururmm/build-shared.sh` |
| Linux build script | `/opt/gururmm/build-linux.sh` |
| Windows build script | `/opt/gururmm/build-windows.sh` |
| Mac build script | `/opt/gururmm/build-mac.sh` |
| Pluto known-hosts | `/opt/gururmm/pluto_known_hosts` |
| Linux build log | `/var/log/gururmm-build-linux.log` |
| Windows build log | `/var/log/gururmm-build-windows.log` |
| Distribution dir | `/var/www/gururmm/downloads/` |
| Per-platform last SHA | `/opt/gururmm/last-built-commit-{linux,windows,mac}` |
| Lock files | `/var/run/gururmm-build-{linux,windows,mac}.lock` |
| Pluto machine doc | `.claude/machines/pluto.md` |

971
session-logs/2026-05-24-session.md
View File

File diff suppressed because one or more lines are too long