sync: auto-sync from HOWARD-HOME at 2026-06-22 18:54:25

Author: Howard Enos
Machine: HOWARD-HOME
Timestamp: 2026-06-22 18:54:25

session-logs/2026-06/2026-06-22-howard-gururmm-software-uninstall.md

@@ -0,0 +1,175 @@
+## User
+- **User:** Howard Enos (howard)
+- **Machine:** Howard-Home
+- **Role:** tech
+
+## Session Summary
+
+Built the GuruRMM remote software-uninstall feature (SPEC-030) end to end, starting
+from Howard's reference to `dUninstaller.exe` (a closed-source Codejock GUI binary —
+nothing to lift). Confirmed the agent already inventories installed software and has a
+robust command pipeline, so the gap was: capture uninstall metadata, an uninstall
+engine, and a dashboard. Shaped the feature via `/shape-spec` into
+`projects/msp-tools/guru-rmm/specs/remote-software-uninstall/`, then prototyped a
+standalone PowerShell engine (`agent/scripts/uninstall-engine.ps1`) implementing a
+silent-first tier ladder (MSI `/qn`, QuietUninstallString, detected NSIS/InnoSetup
+switch, winget), validated by dry-run across 67 real programs and a live `-List` on
+test box DESKTOP-MS42HNC.
+
+Chose "Route B" (server-orchestrated): the server embeds the engine via `include_str!`
+and dispatches it over the existing `powershell` command pipeline — no agent rebuild or
+redeploy. Built `server/src/api/software.rs` (`GET /software`, `POST /software/uninstall`)
++ dashboard `SoftwareManager.tsx` in the Inventory tab (multi-select, confirm-gated bulk
+uninstall, per-program results). Merged to main (PR #47, #48) and deployed; verified live
+by removing Everything and FastStone on DESKTOP-MS42HNC through the real endpoints.
+
+Then layered the removal knowledge loop: a per-agent tracking table (migration 061) and,
+after Howard refined the model, a fleet knowledge catalog (migration 062,
+`software_knowledge`) with three classifications — silent / requires_ui / unknown — keyed
+by exact DisplayName, logs kept only for unknowns, dashboard promotion of unknowns. Added
+BCU (Bulk Crap Uninstaller, Apache-2.0) informed engine upgrades: NSIS detection by binary
+signature, MSI `REBOOT=ReallySuppress` + WiX Package Cache, fail-fast 120s timeout, and a
+critical exit-code-capture fix (`Start-Process -PassThru` left `.ExitCode` null →
+everything falsely reported success; switched to `System.Diagnostics.Process`). Ran a
+multi-round live test battery (MSI, NSIS x2, quiet, vendor Firefox/OneDrive, interactive
+AnyDesk, MSI-1605 path) — all correct, removals verified.
+
+Captured three follow-on designs as specs: GuruConnect SPEC-019 (private Backstage GUI
+desktop for interactive uninstall), rip-and-replace Tier 1.4 (vendor AV/RMM removal tools
+for client takeovers), and Tier 1.5 (BCU-style headless UI automator). Fixed a fleet-wide
+`sync.sh` bug that was repeatedly clobbering submodule branch work. Finished with a scoped
+3-pass Opus audit (`/rmm-audit`) of the SPEC-030 code against GuruRMM standards; fixed all
+HIGH + MEDIUM findings. The engine/catalog work remains on branch
+`feat/engine-bcu-improvements` (pushed, NOT merged — Howard wants more validation first).
+
+## Key Decisions
+
+- **Route B (server-orchestrated) over a native agent command type.** The server embeds
+  the validated engine and dispatches it via the existing `powershell` pipeline, so the
+  feature works on the currently-deployed agent with no rebuild/redeploy. The native
+  command-type port is a later internal refactor behind the same REST shape.
+- **Windows-only for now; show-only on other OSs.** Removal is gated to Windows agents
+  (server returns 501 for non-Windows; dashboard shows the live uninstall UI only on
+  Windows and a read-only installed-software list elsewhere). Linux/macOS removal is a
+  tracked follow-on.
+- **Knowledge catalog keyed by exact DisplayName**, three states (silent/requires_ui/
+  unknown); logs saved ONLY for unknown (undocumented) installers; promotion of unknowns
+  done via a dashboard action (silent methods still added in engine code, not data-driven).
+- **Use vendors' own removal tools for AV/RMM rip-and-replace** (Avast clear, McAfee MCPR,
+  etc.) rather than reverse-engineering; host vetted checksummed copies on our infra.
+- **GuruConnect owns interactive (Tier-2) removal** — silent removal is figured out first;
+  SPEC-019 extends the existing SPEC-013 backstage from terminal to a private GUI desktop.
+- **Engine exits 0 on per-target failures** (failures reported in JSON, not exit code) so
+  one failed program can't fail a whole bulk batch.
+- **Fleet knowledge endpoints are admin-only** (cross-tenant logs + shared writes), matching
+  the `list_commands` convention.
+
+## Problems Encountered
+
+- **sync.sh repeatedly reset the guru-rmm submodule**, discarding committed branch work
+  mid-build (HEAD jumped to a stale pinned commit twice). Root cause: Phase-3 post-rebase
+  ran `git submodule update --init --recursive` unconditionally. Fixed with
+  `submodule_update_safe()` that skips any submodule on a branch or with uncommitted
+  changes; pushed to parent main so the whole fleet gets it. Recovered orphaned commits via
+  cherry-pick onto a feature branch.
+- **AnyDesk `--uninstall --silent` hung ~5+ min** (silent flag not honored on the tested
+  build). Dropped the AnyDesk vendor rule → it now classifies as needs_remote instantly
+  (interactive tier, no launch). Logged as a correction.
+- **Exit codes were not captured** — `Start-Process -PassThru` returned `.ExitCode` null,
+  so every uninstall mapped to exit 0 / false "success" (a failed MSI 1603 would read as
+  removed). Switched to `System.Diagnostics.Process` with async stream reads; verified
+  1605 + exit-0 now captured.
+- **Engine embedded in server but the server build change-gate only watched `server/`** —
+  an engine-only change would silently ship the old engine. Fixed `build-server.sh` to also
+  watch `agent/scripts/uninstall-engine.ps1`.
+- **Git-Bash `curl` started failing "Permission denied"** (AV/EDR on the workstation after
+  many calls). Pivoted RMM API calls to PowerShell `Invoke-RestMethod`.
+- **Hand-built JSON with `C:\\` backslashes was mangled** in Git-Bash (collapsed to single
+  backslash → invalid JSON, ConvertFrom-Json failed). Fixed by building targets JSON with
+  `jq` / extracting from already-valid JSON. Logged as friction.
+- **PR auto-create failed** — `vault.sh get-field services/gitea credentials.api-token`
+  mis-resolved (returned 4 chars). Worked around by parsing the api-token line directly;
+  validated against the Gitea API before use.
+
+## Configuration Changes
+
+Branch `feat/engine-bcu-improvements` (guru-rmm submodule, pushed, NOT merged):
+- `agent/scripts/uninstall-engine.ps1` — new engine (tiers, vendor table, binary-NSIS,
+  Package Cache, fail-fast, exit-code fix, hardened self-uninstall guard)
+- `server/src/api/software.rs` — endpoints (list/uninstall/removal-status/resolve/
+  knowledge/classify), os_type gate, admin gating, error-leak fixes, pagination
+- `server/src/api/mod.rs` — routes
+- `server/src/db/software_removal.rs`, `server/src/db/software_knowledge.rs`, `db/mod.rs`
+- `server/migrations/061_software_removal_attempts.sql`, `062_software_knowledge.sql`
+- `dashboard/src/api/client.ts`, `dashboard/src/components/SoftwareManager.tsx`,
+  `dashboard/src/components/InventoryTab.tsx`, `dashboard/src/pages/AgentDetail.tsx`
+- `deploy/build-pipeline/build-server.sh` — change-gate watches the embedded engine
+- `specs/remote-software-uninstall/` — plan, shape, references, standards, task1-results,
+  bcu-research-and-tiers, knowledge-base-design, rip-and-replace-removal-tools
+- `reports/2026-06-22-spec030-software-uninstall-audit.md`
+
+Already on guru-rmm main (deployed): base inventory+uninstall + per-device tracking
+(PR #47 merge 42681f2c, PR #48 merge c4c0ea7).
+
+guru-connect submodule: `docs/specs/SPEC-019-private-backstage-session.md` +
+`docs/FEATURE_ROADMAP.md` on branch `feat/spec-019-backstage-uninstall` (pushed, off main).
+
+Parent claudetools (pushed to main): `.claude/scripts/sync.sh` (submodule_update_safe),
+`.claude/memory/feedback_submodule_autosync_discipline.md`, `errorlog.md`.
+
+## Credentials & Secrets
+
+- No new credentials created. RMM admin creds read from vault
+  `infrastructure/gururmm-server.sops.yaml` fields
+  `credentials.gururmm-api.admin-email` / `admin-password` (used for API auth during
+  testing). Gitea API token at `services/gitea` field `credentials.api-token` (used for
+  PR create/merge). Temp credential files written under `.claude/tmp/` during testing were
+  shredded; `.claude/tmp` is gitignored.
+
+## Infrastructure & Servers
+
+- GuruRMM API/server: `http://172.16.3.30:3001` (prod; also the build host, user `guru`,
+  repo `/home/guru/gururmm`). Beta dashboard: `https://rmm-beta.azcomputerguru.com`
+  (built from main, talks to prod API). Prod dashboard: `https://rmm.azcomputerguru.com`.
+- Gitea internal API: `http://172.16.3.20:3000` (repo `azcomputerguru/gururmm`,
+  `azcomputerguru/guru-connect`). Public host `git.azcomputerguru.com` is behind
+  Cloudflare (blocks curl).
+- Test box: **DESKTOP-MS42HNC** — AZ Computer Guru / Howard-VM, Windows, agent id
+  `0de89b88-b21d-4647-ab64-96157ba87cc5`.
+
+## Commands & Outputs
+
+- Run engine standalone: `powershell -NoProfile -ExecutionPolicy Bypass -File
+  agent/scripts/uninstall-engine.ps1 -List` (JSON inventory) /
+  `... -TargetsJson <file> [-DryRun]`.
+- Server build check: `SQLX_OFFLINE=true cargo check -p gururmm-server` (clean).
+- Dashboard: `npx tsc -p tsconfig.app.json --noEmit` + `npm run build` (clean).
+- Live results: classification 104/120 silent-capable on DESKTOP-MS42HNC; removed
+  Everything, FastStone, HandBrake, ImgBurn, Paint.NET, GIMP, Firefox, OneDrive, AIMP
+  (verified gone); AnyDesk correctly retained as needs_remote; fake-GUID MSI → exit 1605
+  "not installed".
+- Gitea PR+merge via `Invoke-RestMethod` / token from vault api-token line.
+
+## Pending / Incomplete Tasks
+
+- **Merge + deploy `feat/engine-bcu-improvements`** (engine improvements + knowledge
+  catalog + audit fixes). Not merged per Howard ("keep testing before live"). Post-deploy:
+  verify catalog populates + promote an unknown live; the catalog/dashboard cannot be
+  exercised end-to-end until deployed (live server still runs the old engine).
+- **Audit LOW items** (tracked in the report): `warn!` on audit-write failure, randomized
+  temp filename, TS interface completeness, empty-states, ASCII em-dash/ellipsis cleanup.
+- **GuruConnect SPEC-019** (private Backstage GUI desktop) — branch pushed, not merged.
+- **Rip-and-replace Tier 1.4** (AV/RMM vendor removal tools) — spec written, not built.
+- **Tier 1.5** (headless UI automator) — spec written, not built.
+- **Linux/macOS removal** — Windows-only today; tracked follow-on.
+
+## Reference Information
+
+- Branch: `feat/engine-bcu-improvements` (guru-rmm) — latest commit `c982352`.
+- Merged to guru-rmm main: PR #47 (`42681f2c`), PR #48 (`c4c0ea7`).
+- guru-connect branch: `feat/spec-019-backstage-uninstall`; SPEC-019.
+- Parent commits: `9108f94` (sync fix), `7ad4353` (memory).
+- Specs: `projects/msp-tools/guru-rmm/specs/remote-software-uninstall/` (8 docs).
+- Audit report: `projects/msp-tools/guru-rmm/reports/2026-06-22-spec030-software-uninstall-audit.md`.
+- BCUninstaller (Apache-2.0): https://github.com/BCUninstaller/Bulk-Crap-Uninstaller
+- Engine embed path: server `include_str!("../../../agent/scripts/uninstall-engine.ps1")`.