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:
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