refactor(store): wave B.10 — user_group repo (#263)

UserGroupRepo covers the read side of user_groups_projection and
user_group_members_projection:

  Get / GetByName / GetWithMembers / List / Count /
  ListForUser / ListMemberIDs / ListMembers

UserGroupWithMembers pairs the projection row with the JOIN-computed
ActualMemberCount so SCIM handlers can reconcile against projection
lag. MaintenanceWindow stays as json.RawMessage at the boundary per
the JSONB normalize plan in #242.

Call sites migrated:
- internal/api/user_group_handler.go — ~20 sites + userGroupToProto
  signature shifted to store.UserGroup
- internal/scim/groups_helpers.go — 2 sites
- internal/search/index.go — 1 site (group reindex sweep)

Non-goals:
- GetUserGroupRoles / UserGroupHasRole — Role-domain queries by
  group ID, will be added to RoleRepo in a follow-up wave.
- EvaluateDynamicUserGroup / EvaluateQueuedDynamicUserGroups /
  ValidateUserGroupQuery — call PL/pgSQL, move with Wave C
  (dynamic-query interpreter port).
- Write-side projector queries — stay on Queries() per pattern.

Closes #263.

Author: PaulDotterer

internal/api/assignment_handler.go

@@ -105,7 +105,7 @@ func (h *AssignmentHandler) CreateAssignment(ctx context.Context, req *connect.R
 			return nil, apiErrorCtx(ctx, ErrInternal, connect.CodeInternal, "failed to get user")
 		}
 	case pm.AssignmentTargetType_ASSIGNMENT_TARGET_TYPE_USER_GROUP:
-		_, err := h.store.Queries().GetUserGroupByID(ctx, req.Msg.TargetId)
+		_, err := h.store.Repos().UserGroup.Get(ctx, req.Msg.TargetId)
 		if err != nil {
 			if store.IsNotFound(err) {
 				return nil, apiErrorCtx(ctx, ErrUserGroupNotFound, connect.CodeNotFound, "user group not found")

internal/api/user_group_handler.go

@@ -43,7 +43,7 @@ func (h *UserGroupHandler) CreateUserGroup(ctx context.Context, req *connect.Req
 	// Check name uniqueness — distinguishing NotFound from a transient
 	// DB error matters: silently treating any error as "name available"
 	// would let a concurrent CreateUserGroup succeed twice on a flaky DB.
-	_, err := h.store.Queries().GetUserGroupByName(ctx, req.Msg.Name)
+	_, err := h.store.Repos().UserGroup.GetByName(ctx, req.Msg.Name)
 	if err == nil {
 		return nil, apiErrorCtx(ctx, ErrUserGroupNameExists, connect.CodeAlreadyExists, "user group name already exists")
 	}
@@ -88,7 +88,7 @@ func (h *UserGroupHandler) CreateUserGroup(ctx context.Context, req *connect.Req
 		return nil, err
 	}
 
-	group, err := h.store.Queries().GetUserGroupByID(ctx, id)
+	group, err := h.store.Repos().UserGroup.Get(ctx, id)
 	if err != nil {
 		return nil, apiErrorCtx(ctx, ErrInternal, connect.CodeInternal, "failed to read user group")
 	}
@@ -104,7 +104,7 @@ func (h *UserGroupHandler) GetUserGroup(ctx context.Context, req *connect.Reques
 		return nil, err
 	}
 
-	group, err := h.store.Queries().GetUserGroupByID(ctx, req.Msg.Id)
+	group, err := h.store.Repos().UserGroup.Get(ctx, req.Msg.Id)
 	if err != nil {
 		return nil, handleGetError(ctx, err, ErrUserGroupNotFound, "user group not found")
 	}
@@ -114,7 +114,7 @@ func (h *UserGroupHandler) GetUserGroup(ctx context.Context, req *connect.Reques
 		return nil, apiErrorCtx(ctx, ErrInternal, connect.CodeInternal, "failed to get group roles")
 	}
 
-	members, err := h.store.Queries().ListUserGroupMembers(ctx, req.Msg.Id)
+	members, err := h.store.Repos().UserGroup.ListMembers(ctx, req.Msg.Id)
 	if err != nil {
 		return nil, apiErrorCtx(ctx, ErrInternal, connect.CodeInternal, "failed to get group members")
 	}
@@ -143,15 +143,12 @@ func (h *UserGroupHandler) ListUserGroups(ctx context.Context, req *connect.Requ
 		return nil, err
 	}
 
-	groups, err := h.store.Queries().ListUserGroups(ctx, db.ListUserGroupsParams{
-		Limit:  pageSize,
-		Offset: offset,
-	})
+	groups, err := h.store.Repos().UserGroup.List(ctx, store.ListUserGroupsFilter{Limit: pageSize, Offset: offset})
 	if err != nil {
 		return nil, apiErrorCtx(ctx, ErrInternal, connect.CodeInternal, "failed to list user groups")
 	}
 
-	count, err := h.store.Queries().CountUserGroups(ctx)
+	count, err := h.store.Repos().UserGroup.Count(ctx)
 	if err != nil {
 		return nil, apiErrorCtx(ctx, ErrInternal, connect.CodeInternal, "failed to count user groups")
 	}
@@ -178,7 +175,7 @@ func (h *UserGroupHandler) UpdateUserGroup(ctx context.Context, req *connect.Req
 		return nil, err
 	}
 
-	_, err := h.store.Queries().GetUserGroupByID(ctx, req.Msg.GroupId)
+	_, err := h.store.Repos().UserGroup.Get(ctx, req.Msg.GroupId)
 	if err != nil {
 		return nil, handleGetError(ctx, err, ErrUserGroupNotFound, "user group not found")
 	}
@@ -202,7 +199,7 @@ func (h *UserGroupHandler) UpdateUserGroup(ctx context.Context, req *connect.Req
 		return nil, err
 	}
 
-	updated, err := h.store.Queries().GetUserGroupByID(ctx, req.Msg.GroupId)
+	updated, err := h.store.Repos().UserGroup.Get(ctx, req.Msg.GroupId)
 	if err != nil {
 		return nil, apiErrorCtx(ctx, ErrInternal, connect.CodeInternal, "failed to read user group")
 	}
@@ -235,7 +232,7 @@ func (h *UserGroupHandler) SetUserGroupMaintenanceWindow(ctx context.Context, re
 		return nil, apiErrorCtx(ctx, ErrValidationFailed, connect.CodeInvalidArgument, err.Error())
 	}
 
-	if _, err := h.store.Queries().GetUserGroupByID(ctx, req.Msg.Id); err != nil {
+	if _, err := h.store.Repos().UserGroup.Get(ctx, req.Msg.Id); err != nil {
 		return nil, handleGetError(ctx, err, ErrUserGroupNotFound, "user group not found")
 	}
 
@@ -252,7 +249,7 @@ func (h *UserGroupHandler) SetUserGroupMaintenanceWindow(ctx context.Context, re
 		return nil, err
 	}
 
-	updated, err := h.store.Queries().GetUserGroupByID(ctx, req.Msg.Id)
+	updated, err := h.store.Repos().UserGroup.Get(ctx, req.Msg.Id)
 	if err != nil {
 		return nil, apiErrorCtx(ctx, ErrInternal, connect.CodeInternal, "failed to read user group")
 	}
@@ -270,7 +267,7 @@ func (h *UserGroupHandler) DeleteUserGroup(ctx context.Context, req *connect.Req
 		return nil, err
 	}
 
-	_, err := h.store.Queries().GetUserGroupByID(ctx, req.Msg.Id)
+	_, err := h.store.Repos().UserGroup.Get(ctx, req.Msg.Id)
 	if err != nil {
 		return nil, handleGetError(ctx, err, ErrUserGroupNotFound, "user group not found")
 	}
@@ -399,7 +396,7 @@ func (h *UserGroupHandler) RemoveUserFromGroup(ctx context.Context, req *connect
 	}
 
 	// Verify group exists and is not dynamic
-	group, err := h.store.Queries().GetUserGroupByID(ctx, req.Msg.GroupId)
+	group, err := h.store.Repos().UserGroup.Get(ctx, req.Msg.GroupId)
 	if err != nil {
 		return nil, handleGetError(ctx, err, ErrUserGroupNotFound, "user group not found")
 	}
@@ -583,7 +580,7 @@ func (h *UserGroupHandler) ListUserGroupsForUser(ctx context.Context, req *conne
 		return nil, handleGetError(ctx, err, ErrUserNotFound, "user not found")
 	}
 
-	groups, err := h.store.Queries().ListUserGroupsForUser(ctx, req.Msg.UserId)
+	groups, err := h.store.Repos().UserGroup.ListForUser(ctx, req.Msg.UserId)
 	if err != nil {
 		return nil, apiErrorCtx(ctx, ErrInternal, connect.CodeInternal, "failed to list user groups")
 	}
@@ -639,7 +636,7 @@ func (h *UserGroupHandler) UpdateUserGroupQuery(ctx context.Context, req *connec
 		return nil, err
 	}
 
-	group, err := h.store.Queries().GetUserGroupByID(ctx, req.Msg.Id)
+	group, err := h.store.Repos().UserGroup.Get(ctx, req.Msg.Id)
 	if err != nil {
 		return nil, handleGetError(ctx, err, ErrUserGroupNotFound, "user group not found")
 	}
@@ -700,7 +697,7 @@ func (h *UserGroupHandler) EvaluateDynamicUserGroup(ctx context.Context, req *co
 	}
 
 	// Verify group exists and is dynamic
-	group, err := h.store.Queries().GetUserGroupByID(ctx, req.Msg.Id)
+	group, err := h.store.Repos().UserGroup.Get(ctx, req.Msg.Id)
 	if err != nil {
 		return nil, handleGetError(ctx, err, ErrUserGroupNotFound, "user group not found")
 	}
@@ -719,7 +716,7 @@ func (h *UserGroupHandler) EvaluateDynamicUserGroup(ctx context.Context, req *co
 	}
 
 	// Get updated group
-	group, err = h.store.Queries().GetUserGroupByID(ctx, req.Msg.Id)
+	group, err = h.store.Repos().UserGroup.Get(ctx, req.Msg.Id)
 	if err != nil {
 		return nil, apiErrorCtx(ctx, ErrInternal, connect.CodeInternal, "failed to get user group")
 	}
@@ -786,7 +783,7 @@ func (h *UserGroupHandler) bumpUserSessionVersion(ctx context.Context, userID, a
 // failing member does not prevent the remaining members from being
 // invalidated. A partial bump is better than stopping early.
 func (h *UserGroupHandler) bumpSessionVersionForGroupMembers(ctx context.Context, groupID, actorID string) error {
-	memberIDs, err := h.store.Queries().ListUserGroupMemberIDs(ctx, groupID)
+	memberIDs, err := h.store.Repos().UserGroup.ListMemberIDs(ctx, groupID)
 	if err != nil {
 		return err
 	}
@@ -802,7 +799,7 @@ func (h *UserGroupHandler) bumpSessionVersionForGroupMembers(ctx context.Context
 }
 
 // userGroupToProto converts a database user group projection to a protobuf UserGroup.
-func userGroupToProto(g db.UserGroupsProjection, roles []db.RolesProjection, isScimManaged bool) *pm.UserGroup {
+func userGroupToProto(g store.UserGroup, roles []db.RolesProjection, isScimManaged bool) *pm.UserGroup {
 	group := &pm.UserGroup{
 		Id:                g.ID,
 		Name:              g.Name,

internal/scim/groups_helpers.go

@@ -20,7 +20,7 @@ import (
 // member set twice produces no second-round events.
 func (h *Handler) reconcileGroupMembers(ctx context.Context, provider store.IdentityProvider, groupID string, requestedMembers []SCIMMember) {
 	h.logger.Debug("SCIM reconcileGroupMembers", "group_id", groupID, "requested_count", len(requestedMembers))
-	currentMemberIDs, err := h.store.Queries().ListUserGroupMemberIDs(ctx, groupID)
+	currentMemberIDs, err := h.store.Repos().UserGroup.ListMemberIDs(ctx, groupID)
 	if err != nil {
 		h.logger.Error("failed to list current group members for reconciliation", "error", err)
 		return
@@ -82,20 +82,20 @@ func (h *Handler) reconcileGroupMembers(ctx context.Context, provider store.Iden
 // If the user group was deleted but the mapping still exists (orphaned), it re-creates
 // the user group and updates the mapping to restore consistency.
 func (h *Handler) buildGroupResource(ctx context.Context, providerID string, mapping store.SCIMGroupMapping, baseURL string) (SCIMGroup, error) {
-	group, err := h.store.Queries().GetUserGroupWithMembers(ctx, mapping.UserGroupID)
+	group, err := h.store.Repos().UserGroup.GetWithMembers(ctx, mapping.UserGroupID)
 	if store.IsNotFound(err) {
 		// User group was deleted but SCIM mapping still exists — restore it.
 		mapping, err = h.restoreOrphanedGroup(ctx, providerID, mapping)
 		if err != nil {
 			return SCIMGroup{}, fmt.Errorf("restore orphaned group: %w", err)
 		}
-		group, err = h.store.Queries().GetUserGroupWithMembers(ctx, mapping.UserGroupID)
+		group, err = h.store.Repos().UserGroup.GetWithMembers(ctx, mapping.UserGroupID)
 	}
 	if err != nil {
 		return SCIMGroup{}, fmt.Errorf("get user group: %w", err)
 	}
 
-	memberIDs, err := h.store.Queries().ListUserGroupMemberIDs(ctx, mapping.UserGroupID)
+	memberIDs, err := h.store.Repos().UserGroup.ListMemberIDs(ctx, mapping.UserGroupID)
 	if err != nil {
 		return SCIMGroup{}, fmt.Errorf("list group members: %w", err)
 	}

internal/scim/groups_mutate.go

@@ -290,7 +290,7 @@ func (h *Handler) handleGroupPatchReplace(ctx context.Context, provider store.Id
 			requestedSet[id] = true
 		}
 
-		currentMemberIDs, err := h.store.Queries().ListUserGroupMemberIDs(ctx, groupID)
+		currentMemberIDs, err := h.store.Repos().UserGroup.ListMemberIDs(ctx, groupID)
 		if err != nil {
 			h.logger.Error("failed to list group members for patch replace", "group_id", groupID, "error", err)
 			return

internal/search/index.go

@@ -835,10 +835,7 @@ func (idx *Index) warmUserGroups(ctx context.Context) (int, error) {
 	var total int
 
 	for {
-		groups, err := idx.store.Queries().ListUserGroups(ctx, db.ListUserGroupsParams{
-			Limit:  pageSize,
-			Offset: offset,
-		})
+		groups, err := idx.store.Repos().UserGroup.List(ctx, store.ListUserGroupsFilter{Limit: pageSize, Offset: offset})
 		if err != nil {
 			return total, err
 		}

internal/store/postgres/user_group.go

@@ -0,0 +1,133 @@
+package postgres
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+
+	"github.com/manchtools/power-manage/server/internal/store"
+	"github.com/manchtools/power-manage/server/internal/store/generated"
+)
+
+// UserGroup implements store.UserGroupRepo against
+// user_groups_projection + user_group_members_projection.
+type UserGroup struct {
+	q *generated.Queries
+}
+
+// NewUserGroup returns a UserGroup repo bound to the given sqlc handle.
+func NewUserGroup(q *generated.Queries) *UserGroup {
+	return &UserGroup{q: q}
+}
+
+func (g *UserGroup) Get(ctx context.Context, id string) (store.UserGroup, error) {
+	row, err := g.q.GetUserGroupByID(ctx, id)
+	if err != nil {
+		return store.UserGroup{}, fmt.Errorf("user_group: get: %w", translateNotFound(err))
+	}
+	return userGroupFromRow(row), nil
+}
+
+func (g *UserGroup) GetByName(ctx context.Context, name string) (store.UserGroup, error) {
+	row, err := g.q.GetUserGroupByName(ctx, name)
+	if err != nil {
+		return store.UserGroup{}, fmt.Errorf("user_group: get by name: %w", translateNotFound(err))
+	}
+	return userGroupFromRow(row), nil
+}
+
+func (g *UserGroup) GetWithMembers(ctx context.Context, id string) (store.UserGroupWithMembers, error) {
+	row, err := g.q.GetUserGroupWithMembers(ctx, id)
+	if err != nil {
+		return store.UserGroupWithMembers{}, fmt.Errorf("user_group: get with members: %w", translateNotFound(err))
+	}
+	return store.UserGroupWithMembers{
+		UserGroup: store.UserGroup{
+			ID:                row.ID,
+			Name:              row.Name,
+			Description:       row.Description,
+			MemberCount:       row.MemberCount,
+			CreatedAt:         row.CreatedAt,
+			CreatedBy:         row.CreatedBy,
+			UpdatedAt:         row.UpdatedAt,
+			IsDynamic:         row.IsDynamic,
+			DynamicQuery:      row.DynamicQuery,
+			MaintenanceWindow: json.RawMessage(row.MaintenanceWindow),
+		},
+		ActualMemberCount: row.ActualMemberCount,
+	}, nil
+}
+
+func (g *UserGroup) List(ctx context.Context, filter store.ListUserGroupsFilter) ([]store.UserGroup, error) {
+	rows, err := g.q.ListUserGroups(ctx, generated.ListUserGroupsParams{
+		Limit:  filter.Limit,
+		Offset: filter.Offset,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("user_group: list: %w", err)
+	}
+	out := make([]store.UserGroup, len(rows))
+	for i, r := range rows {
+		out[i] = userGroupFromRow(r)
+	}
+	return out, nil
+}
+
+func (g *UserGroup) Count(ctx context.Context) (int64, error) {
+	n, err := g.q.CountUserGroups(ctx)
+	if err != nil {
+		return 0, fmt.Errorf("user_group: count: %w", translateNotFound(err))
+	}
+	return n, nil
+}
+
+func (g *UserGroup) ListForUser(ctx context.Context, userID string) ([]store.UserGroup, error) {
+	rows, err := g.q.ListUserGroupsForUser(ctx, userID)
+	if err != nil {
+		return nil, fmt.Errorf("user_group: list for user: %w", err)
+	}
+	out := make([]store.UserGroup, len(rows))
+	for i, r := range rows {
+		out[i] = userGroupFromRow(r)
+	}
+	return out, nil
+}
+
+func (g *UserGroup) ListMemberIDs(ctx context.Context, groupID string) ([]string, error) {
+	ids, err := g.q.ListUserGroupMemberIDs(ctx, groupID)
+	if err != nil {
+		return nil, fmt.Errorf("user_group: list member ids: %w", err)
+	}
+	return ids, nil
+}
+
+func (g *UserGroup) ListMembers(ctx context.Context, groupID string) ([]store.UserGroupMember, error) {
+	rows, err := g.q.ListUserGroupMembers(ctx, groupID)
+	if err != nil {
+		return nil, fmt.Errorf("user_group: list members: %w", err)
+	}
+	out := make([]store.UserGroupMember, len(rows))
+	for i, r := range rows {
+		out[i] = store.UserGroupMember{
+			UserID:  r.UserID,
+			Email:   r.Email,
+			AddedAt: r.AddedAt,
+		}
+	}
+	return out, nil
+}
+
+func userGroupFromRow(r generated.UserGroupsProjection) store.UserGroup {
+	return store.UserGroup{
+		ID:                r.ID,
+		Name:              r.Name,
+		Description:       r.Description,
+		MemberCount:       r.MemberCount,
+		CreatedAt:         r.CreatedAt,
+		CreatedBy:         r.CreatedBy,
+		UpdatedAt:         r.UpdatedAt,
+		IsDynamic:         r.IsDynamic,
+		DynamicQuery:      r.DynamicQuery,
+		MaintenanceWindow: json.RawMessage(r.MaintenanceWindow),
+	}
+}

internal/store/postgres/wire.go

@@ -28,6 +28,7 @@ func NewRepos(q *generated.Queries) *store.Repos {
 		TerminalSession:  NewTerminalSession(q),
 		Token:            NewToken(q),
 		Totp:             NewTotp(q),
+		UserGroup:        NewUserGroup(q),
 		UserSelection:    NewUserSelection(q),
 	}
 }

internal/store/repos.go

@@ -27,5 +27,6 @@ type Repos struct {
 	TerminalSession  TerminalSessionRepo
 	Token            TokenRepo
 	Totp             TotpRepo
+	UserGroup        UserGroupRepo
 	UserSelection    UserSelectionRepo
 }