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`.