power-manage-sdk

Overview

The SDK defines the contract between all power-manage components. Three layers:

1. Protobuf definitions (proto/pm/v1/) — 6 proto files, 178 RPCs total.
2. Generated code (gen/go/, gen/ts/) — Go + TypeScript stubs from buf generate.
3. Capability library (27 Go packages) — dependency-injected system management.

Module path: github.com/manchtools/power-manage-sdk (Go 1.25).

Proto surface

File catalog

RPC distribution

Proto conventions

• Every field crossing a trust boundary carries @gotags validate:"..." tag. Required, ulid, min_len, max_len, gt, pattern, required_if constraints.
• IDs are ULIDs — string value = 1 with validate:"required,ulid".
• Enums start at 1 — proto3 requires 0 for unspecified default.
• oneof for action parameters — 23 action types, each with its own params message inside a oneof field.
• Backward compatibility enforced by buf breaking against main branch. Field numbers are frozen once released.

Generated code

Go (gen/go/pm/v1/)

Produces message structs with @gotags validate tags, Connect-RPC clients and handlers, and JSON/proto marshaling. Package pmv1.

TypeScript (gen/ts/pm/)

Produces ES module classes, Connect-RPC transport-agnostic clients (createPromiseClient), and TypeScript types. Uses @bufbuild/protoc-gen-es and @connectrpc/protoc-gen-connect-es.

Regeneration

cd sdk && make generate   # both Go and TypeScript

CI verifies regeneration produces no diff.

Capability library

27 Go packages organized by system domain. Every capability follows the injected shape: Runner + Backend → Manager.

Design principles

1. Explicit over clever — the caller names the privilege tool (exec.Sudo, exec.Direct, exec.Doas) and backend (pkg.Apt, service.Systemd).
2. No global state — backend selection lives on the instance.
3. Testable without a host — FakeRunner asserts exact argv shapes.
4. Mutations return exec.Result — stdout, stderr, exit code.

Package catalog

Testing infrastructure

Shared infrastructure

Adversarial testing

adversary/ package: attack simulations verifying protocol invariants — forged task HMAC, key substitution, cross-actor binding, replay, downgrade.

Container test strategy (proposed)

Multi-distro Docker stages in test/Dockerfile.{debian,fedora,opensuse,archlinux}. Each stage is a known system state (stale lock, degraded service, missing tools). Tests run real binaries against known states. See docs/02-concepts/02-backends.md.

Invariants

1. Proto files are the source of truth. Generated code never hand-edited.
2. Every proto field crossing a trust boundary has a validate tag.
3. buf breaking must pass against main. Backward compatible.
4. No global state in the capability library. All injected.
5. Backend selection is explicit. Never auto-detect.
6. All crypto calls carry domain-separation info tags.
7. ULIDs for all identifiers. Never crypto.randomUUID().
8. docref anchors for all exported symbols in SDK docs.
9. Roundtrip tests for event payloads — byte-identical marshal/unmarshal.