feat: operational tooling — signing, versioning, changelog, roadmap (SPEC-001)
Establish GuruConnect's release engineering and project tracking (SPEC-001): - docs/ scaffold: FEATURE_ROADMAP, ARCHITECTURE_DECISIONS (ADR-001 standalone+contract, ADR-002 Gitea Actions + Azure Trusted Signing), docs/specs/SPEC-001, CHANGELOG. - .gitea/workflows/release.yml: conventional-commit auto-versioning, git-cliff changelog, Windows agent build, Azure Trusted Signing via jsign (reusing the shared ACG cert profile), Gitea release via REST API. build-and-test.yml is the PR/push gate; deploy.yml de-duplicated. - server: GET /api/changelog/:component/:version (latest + by-version), path-traversal hardened. - cliff.toml; server/.env.example documents CHANGELOG_DIR. Reviewed (Code Review Agent): axum route-conflict blocker fixed; CHANGELOG ordering, toolchain target, breaking-change parsing, empty-changelog fallback addressed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
81
docs/ARCHITECTURE_DECISIONS.md
Normal file
81
docs/ARCHITECTURE_DECISIONS.md
Normal file
@@ -0,0 +1,81 @@
|
||||
# GuruConnect — Architecture Decisions
|
||||
|
||||
Records significant architectural decisions for the GuruConnect product. Each entry: context,
|
||||
decision, options considered, rationale, consequences.
|
||||
|
||||
---
|
||||
|
||||
## ADR-001: GuruConnect is a Standalone Product; Integrate with GuruRMM via a Versioned Contract
|
||||
|
||||
**Date:** 2026-05-29
|
||||
**Status:** Decided
|
||||
**Deciders:** Mike Swanson
|
||||
|
||||
### Context
|
||||
|
||||
GuruConnect is a remote-support product that must work fully on its own, with its own repository
|
||||
(`azcomputerguru/guru-connect`), build pipeline, and release cadence. GuruRMM wants to offer native
|
||||
integrated remote control by driving GuruConnect.
|
||||
|
||||
### Decision
|
||||
|
||||
GuruConnect stays an independent product. It exposes a **versioned integration contract**
|
||||
(`/api/integration/v1/`, capability discovery, embedded-viewer protocol) that GuruRMM consumes as a
|
||||
broker. The two products do not share build pipelines or release in lockstep. GuruConnect owns the
|
||||
contract; GuruRMM does no active development on GuruConnect.
|
||||
|
||||
### Rationale
|
||||
|
||||
- Preserves GuruConnect as a sellable standalone product.
|
||||
- Avoids coupling two independently-evolving codebases; integration changes go through the contract.
|
||||
- Mirrors the GuruRMM-side decision (GuruRMM ADR-008).
|
||||
|
||||
### Consequences
|
||||
|
||||
- The integration surface is semver'd; breaking changes require a major bump.
|
||||
- See `docs/specs/native-remote-control/` for the contract spec.
|
||||
|
||||
---
|
||||
|
||||
## ADR-002: Release Engineering — Gitea Actions Pipeline with Azure Trusted Signing
|
||||
|
||||
**Date:** 2026-05-29
|
||||
**Status:** Decided
|
||||
**Deciders:** Mike Swanson
|
||||
|
||||
### Context
|
||||
|
||||
GuruConnect needs operational parity with GuruRMM: signed Windows binaries, automatic versioning,
|
||||
changelogs, and tracking. GuruRMM achieves this with a Gitea **webhook → shell-script** pipeline on
|
||||
shared build hosts (Saturn + Pluto) and signs via Azure Trusted Signing (`jsign`) using credentials
|
||||
in `/etc/gururmm-signing.env`.
|
||||
|
||||
### Decision
|
||||
|
||||
GuruConnect implements its release engineering **entirely in Gitea Actions** (not the webhook/script
|
||||
model), and **reuses GuruRMM's existing Azure Trusted Signing certificate profile** (same account +
|
||||
service principal) to sign the Windows agent `.exe`.
|
||||
|
||||
### Options Considered
|
||||
|
||||
- **A — Gitea Actions, reuse RMM cert profile (chosen):** self-contained workflows; `jsign` runs on
|
||||
the `ubuntu-latest` runner; no Pluto/webhook dependency. GC ships a single `.exe` (no WiX/MSI), so
|
||||
no Windows runner is needed.
|
||||
- **B — Mirror RMM's webhook + shell scripts:** maximal parity but adds Pluto/webhook coupling and a
|
||||
build host to maintain.
|
||||
- **C — Separate Azure Trusted Signing account for GC:** cleaner attribution, more Azure setup.
|
||||
|
||||
### Rationale
|
||||
|
||||
- `jsign` is cross-platform (Java) and signs PE binaries on Linux — no Windows runner required.
|
||||
- Reusing RMM's cert profile means zero new Azure provisioning; GC binaries are signed by the same
|
||||
ACG identity.
|
||||
- Actions are self-contained and versioned with the repo, simpler than maintaining build-host scripts.
|
||||
|
||||
### Consequences
|
||||
|
||||
- The Azure Trusted Signing service-principal secrets must be added to the `guru-connect` repo's
|
||||
Gitea Actions secrets (values come from `/etc/gururmm-signing.env` / the SOPS vault). See SPEC-001.
|
||||
- Windows binaries will be attributed to GuruRMM's cert profile until/unless a GuruConnect-specific
|
||||
profile is provisioned (a future, low-effort change).
|
||||
- Implementation: `docs/specs/SPEC-001-operational-tooling-parity.md`.
|
||||
60
docs/FEATURE_ROADMAP.md
Normal file
60
docs/FEATURE_ROADMAP.md
Normal file
@@ -0,0 +1,60 @@
|
||||
# GuruConnect — Feature Roadmap
|
||||
|
||||
> Living roadmap for the GuruConnect product. Status markers: `[ ]` planned · `[~]` in
|
||||
> consideration · `[x]` shipped. Priorities: P1 (blocking/MVP) · P2 (important) · P3 (nice-to-have).
|
||||
> Specs live in `docs/specs/SPEC-NNN-<slug>.md`. Decisions in `docs/ARCHITECTURE_DECISIONS.md`.
|
||||
|
||||
GuruConnect is a standalone remote-support product (ScreenConnect/Splashtop-class) on our own Rust
|
||||
stack. It ships independently of GuruRMM and integrates with it via a versioned contract (see
|
||||
`specs/native-remote-control/` and ADR-001).
|
||||
|
||||
---
|
||||
|
||||
## Operational Tooling & Release Engineering
|
||||
|
||||
Bringing GC to parity with GuruRMM's release engineering. Full plan: [SPEC-001](specs/SPEC-001-operational-tooling-parity.md).
|
||||
|
||||
- [ ] **Code signing — Azure Trusted Signing in CI** — P1 — sign the Windows agent `.exe` via `jsign` (TRUSTEDSIGNING) in Gitea Actions, reusing the shared ACG cert profile. (SPEC-001 §2)
|
||||
- [ ] **Automatic versioning** — P1 — conventional-commit-driven version bump across agent/server/dashboard, embedded via `build.rs`. (SPEC-001 §3)
|
||||
- [ ] **Changelog generation & API** — P2 — `CHANGELOG.md` + per-version changelogs from conventional commits, served at `/api/changelog/...`. (SPEC-001 §4)
|
||||
- [ ] **Feature-request workflow** — P2 — `/gc-feature-request` skill producing `docs/specs/SPEC-NNN-*.md` and updating this roadmap. (SPEC-001 §1)
|
||||
- [ ] **Roadmap / ADR / spec tracking** — P1 — this file + `ARCHITECTURE_DECISIONS.md` + `docs/specs/`. (SPEC-001 §5) — *bootstrapped*
|
||||
- [ ] **Coord-API registration** — P3 — register `guruconnect` project_key + components (`server`, `agent`, `dashboard`) in the coordination API. (SPEC-001 §6)
|
||||
- [~] **Release distribution / update channels** — P3 — beta→stable rollout with health metrics (mirrors RMM `updates.rs`). Deferred — larger subsystem, post-parity.
|
||||
|
||||
---
|
||||
|
||||
## Core Remote Control
|
||||
|
||||
- [x] Screen capture (DXGI primary, GDI fallback)
|
||||
- [x] Input injection (mouse/keyboard)
|
||||
- [x] Native viewer + `guruconnect://` protocol handler
|
||||
- [x] Support-code (attended) and persistent (unattended) agent modes
|
||||
- [x] Protobuf-over-WSS transport, Zstd frame compression
|
||||
- [~] React/TS web viewer (`dashboard/src/components/RemoteViewer.tsx`) — embeddable session viewer
|
||||
- [ ] Multi-monitor switching — P2
|
||||
- [ ] File transfer — P3 (out of scope for native-remote-control v1)
|
||||
- [ ] Session recording — P3 (out of scope for native-remote-control v1)
|
||||
|
||||
## GuruRMM Integration
|
||||
|
||||
- [ ] **Native remote control via broker** — P2 — versioned integration contract so GuruRMM can launch/embed GC sessions on managed endpoints. Full spec: [`specs/native-remote-control/`](specs/native-remote-control/). (Contract owned by GC; RMM consumes it.)
|
||||
- [ ] `/api/integration/v1/` namespace + capability discovery — P2 (part of native-remote-control)
|
||||
- [ ] Per-machine agent keys (replace shared `AGENT_API_KEY`) — P2
|
||||
- [ ] Embedded-viewer framing allowlist (scoped `frame-ancestors`) — P2
|
||||
|
||||
## Server / API
|
||||
|
||||
- [x] JWT auth, Argon2id passwords, rate limiting, security headers
|
||||
- [x] Sessions / machines / support-codes / events
|
||||
- [ ] Programmatic session pre-create + viewer-token (integration contract) — P2
|
||||
|
||||
## Security & Infrastructure
|
||||
|
||||
- [x] Phase-1 security hardening (SEC-1..5), systemd units, backups
|
||||
- [ ] CI security audit gate (`cargo audit`) wired to release — P2
|
||||
|
||||
## Future Considerations
|
||||
|
||||
- [ ] macOS / Linux remote-control agents — P3
|
||||
- [ ] Auto-update for the agent — P3
|
||||
117
docs/specs/SPEC-001-operational-tooling-parity.md
Normal file
117
docs/specs/SPEC-001-operational-tooling-parity.md
Normal file
@@ -0,0 +1,117 @@
|
||||
# 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`.
|
||||
Reference in New Issue
Block a user