guru-connect/docs/specs/SPEC-001-operational-tooling-parity.md

SPEC-001: Operational Tooling Parity with GuruRMM

Status: Proposed Priority: P1 Requested By: Mike (2026-05-29) Estimated Effort: Large

---

Overview

Bring GuruConnect's release engineering and project tooling to parity with GuruRMM: signed Windows binaries, automatic versioning, changelog generation, a feature-request workflow, and roadmap/spec tracking. Per ADR-002, this is implemented entirely in Gitea Actions (not RMM's webhook/script model), and reuses RMM's existing Azure Trusted Signing certificate profile.

GC ships a single Windows .exe (no WiX/MSI), so all jobs run on ubuntu-latest — jsign is a Java tool that signs PE binaries on Linux. No Windows runner or Pluto dependency.

Success criteria: a push to main produces an auto-versioned, signed guruconnect.exe with a generated changelog entry; /gc-feature-request produces a SPEC and updates the roadmap.

---

§1 — Feature-request workflow (skill)

Deliverable: /gc-feature-request skill (in .claude/commands/gc-feature-request.md, claudetools repo).

Adapted from RMM's /feature-request:

• Reads docs/FEATURE_ROADMAP.md, docs/ARCHITECTURE_DECISIONS.md, this repo's CLAUDE.md.
• Ollama classification (qwen3.6 JSON) → section/priority; prose spec via qwen3:14b (fallback: self).
• Writes docs/specs/SPEC-NNN-<slug>.md (next number), updates the roadmap, commits in the GC repo.
• GC architecture vocabulary: agent / relay-server / viewer / dashboard (not RMM's agent/server/dashboard).
• Coord messages use project_key: "guruconnect" (see §6).

§2 — Code signing (Azure Trusted Signing in Actions)

Deliverable: a reusable signing step/job in .gitea/workflows/.

Mirror RMM's sign-windows.sh logic inside Actions:

1. Acquire token: POST https://login.microsoftonline.com/${AZURE_TENANT_ID}/oauth2/v2.0/token with grant_type=client_credentials, client_id, client_secret, scope=https://codesigning.azure.net/.default.
2. Install jsign (+ JRE) on the runner.
3. Sign:

   jsign --storetype TRUSTEDSIGNING --keystore "$TS_ENDPOINT" --storepass "$TOKEN" \
         --alias "${TS_ACCOUNT}/${TS_CERT_PROFILE}" --tsaurl "$TS_TIMESTAMP_URL" \
         --tsmode RFC3161 --alg SHA-256 --name "GuruConnect Agent" \
         --url "https://www.azcomputerguru.com" --replace guruconnect.exe
   

4. Emit [OK] signed / on failure fail the release job (do NOT publish unsigned for releases).

Required Gitea Actions secrets on the guru-connect repo (values reused from RMM — /etc/gururmm-signing.env on the build host / SOPS vault; do not hardcode): AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, TS_ENDPOINT, TS_ACCOUNT, TS_CERT_PROFILE, TS_TIMESTAMP_URL.

§3 — Automatic versioning

Deliverable: a version-bump job in the release workflow.

• Canonical versions: agent/Cargo.toml, server/Cargo.toml, dashboard/package.json (all 0.1.0 today).
• On push to main, determine the next version from conventional commits since the last release tag (feat: → minor, fix:/perf: → patch); bump only components whose files changed.
• Commit the bump (chore: release vX.Y.Z [skip ci]) and tag vX.Y.Z. The agent embeds the version via the existing agent/build.rs (already reads CARGO_PKG_VERSION + git hash) — no change needed there.
• Requires a push-capable token secret for the runner (CI_PUSH_TOKEN) to commit the bump/tag back.

§4 — Changelog generation & API

Deliverables: changelog generation in the release workflow + a server endpoint.

• Generate from conventional commits (git-cliff or equivalent) into CHANGELOG.md and changelogs/<component>/v<version>.md, plus changelogs/LATEST_<COMPONENT>.md.
• Server: add GET /api/changelog/:component/latest and GET /api/changelog/:component/:version (mirror RMM server/src/api/changelog.rs), reading from a CHANGELOG_DIR env (default server/changelogs or the deployed downloads path).

§5 — Roadmap / ADR / spec tracking (bootstrapped)

Deliverables (this spec's commit establishes them):

• docs/FEATURE_ROADMAP.md — living roadmap, [ ]/[~]/[x] + P1–P3.
• docs/ARCHITECTURE_DECISIONS.md — ADR-NNN log (ADR-001 standalone+contract, ADR-002 release eng).
• docs/specs/SPEC-NNN-*.md — numbered specs (this is SPEC-001).
• CHANGELOG.md — Keep-a-Changelog seed.

§6 — Coord-API registration

Deliverable: register GC in the coordination API.

• Add guruconnect project_key with components server, agent, dashboard (states: building, built, deploying, deployed, degraded).
• Update root .claude/CLAUDE.md "Project keys" table to include guruconnect.
• /gc-feature-request and CI can then POST component state updates after deploys.

---

Implementation Order

1. §5 docs scaffold (this commit) + §1 skill.
2. §2 signing + §3 versioning + §4 changelog as Gitea Actions workflows (depends on the repo secrets in §2 being added first).
3. §4 server changelog endpoint.
4. §6 coord registration.

Open Questions

• Server version: auto-bump like agent, or keep manual (RMM keeps server manual)? Default: auto-bump all.
• Long term: provision a dedicated "GuruConnect" Azure Trusted Signing cert profile for correct publisher attribution (ADR-002 notes current reuse of RMM's profile).

References

• ADR-002 (this repo), GuruRMM sign-windows.sh (Azure Trusted Signing via jsign), RMM scripts/build-agents.sh (auto-version), scripts/generate-changelog.sh, server/src/api/changelog.rs. Roadmap: docs/FEATURE_ROADMAP.md.